New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Rework on documentation guides #5893
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,25 +1,79 @@ | ||
Adding Custom CSS or JavaScript to a Sphinx Project | ||
=================================================== | ||
Adding Custom CSS or JavaScript to Sphinx Documentation | ||
======================================================= | ||
|
||
The easiest way to add custom stylesheets or scripts, and ensure that the files | ||
are added in a way that allows for overriding of existing styles or scripts, is | ||
to add these files using a ``conf.py`` Sphinx extension. Inside your | ||
``conf.py``, if a function ``setup(app)`` exists, Sphinx will call this function | ||
as a normal extension during application setup. | ||
.. meta:: | ||
:description lang=en: | ||
How to add additional CSS stylesheets or JavaScript files | ||
to your Sphinx documentation | ||
to override your Sphinx theme or add interactivity with JavaScript. | ||
|
||
For example, if a custom stylesheet exists at ``_static/css/custom.css``, a | ||
``conf.py`` extension can be written to add this file to the list of | ||
stylesheets:: | ||
Adding additional CSS or JavaScript files to your Sphinx documentation | ||
can let you customize the look and feel of your docs | ||
or add additional functionality. | ||
For example, with a small snippet of CSS, | ||
your documentation could use a custom font or have a different background color. | ||
|
||
def setup(app): | ||
app.add_stylesheet('css/custom.css') | ||
If your custom stylesheet is ``_static/css/custom.css``, | ||
you can add that CSS file to the documentation using the | ||
Sphinx option `html_css_files`_:: | ||
|
||
Using an extension to add the stylesheet allows for the file to be added to the | ||
list of stylesheets later in the Sphinx setup process, making overriding parts | ||
of the Read the Docs theme possible. | ||
## conf.py | ||
|
||
The same method can be used to add additional scripts that might override | ||
previously initialized scripts:: | ||
# These folders are copied to the documentation's HTML output | ||
html_static_path = ['_static'] | ||
|
||
def setup(app): | ||
app.add_javascript('js/custom.js') | ||
# These paths are either relative to html_static_path | ||
# or fully qualified paths (eg. https://...) | ||
html_css_files = [ | ||
'css/custom.css', | ||
] | ||
|
||
|
||
A similar approach can be used to add JavaScript files:: | ||
|
||
html_js_files = [ | ||
'js/custom.js', | ||
] | ||
|
||
|
||
|
||
.. _html_css_files: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_css_files | ||
|
||
.. note:: | ||
|
||
The Sphinx HTML options ``html_css_files`` and ``html_js_files`` | ||
where added in Sphinx 1.8. | ||
Unless you have a good reason to use an older version, | ||
you are strongly encouraged to upgrade. | ||
Sphinx is almost entirely backwards compatible. | ||
|
||
|
||
Overriding or replacing a theme's stylesheet | ||
-------------------------------------------- | ||
|
||
The above approach is preferred for adding additional stylesheets or JavaScript, | ||
but it is also possible to completely replace a Sphinx theme's stylesheet | ||
with your own stylesheet. | ||
|
||
If your replacement stylesheet exists at ``_static/css/yourtheme.css``, | ||
you can replace your theme's CSS file by setting ``html_style`` in your ``conf.py``:: | ||
|
||
## conf.py | ||
|
||
html_style = 'css/yourtheme.css' | ||
|
||
If you only need to override a few styles on the theme, | ||
you can include the theme's normal CSS using the CSS | ||
`@import rule <https://developer.mozilla.org/en-US/docs/Web/CSS/@import>`_ . | ||
|
||
.. code-block:: css | ||
|
||
/** css/yourtheme.css **/ | ||
|
||
/* This line is theme specific - it includes the base theme CSS */ | ||
@import '../alabaster.css'; /* for Alabaster */ | ||
/*@import 'theme.css'; /* for the Read the Docs theme */ | ||
|
||
body { | ||
/* ... */ | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,11 +1,44 @@ | ||
Guides | ||
====== | ||
|
||
These guides will help walk you through the usage of Read the Docs. | ||
These guides will help walk you through specific use cases | ||
related to Read the Docs itself, documentation tools like Sphinx and MkDocs | ||
and how to write successful documentation. | ||
|
||
|
||
Sphinx & MkDocs how-to guides | ||
----------------------------- | ||
|
||
These guides will help you get the most out of your documentation authoring tool | ||
whether that is Sphinx or MkDocs. | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
|
||
adding-custom-css | ||
custom-404-page | ||
manage-translations | ||
mkdocs-old-versions | ||
pdf-non-ascii-languages | ||
remove-edit-buttons | ||
vcs | ||
|
||
|
||
Read the Docs how-to guides | ||
--------------------------- | ||
|
||
These guides will help you customize or tune aspects of the Read the Docs build environment. | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
:glob: | ||
:maxdepth: 1 | ||
|
||
* | ||
build-notifications | ||
build-using-too-many-resources | ||
canonical | ||
conda | ||
environment-variables | ||
feature-flags | ||
google-analytics | ||
sitemaps | ||
specifying-dependencies | ||
wipe-environment |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do feel like we're making the guides harder to find when we add more nesting to the TOC's. I can almost never find the development docs now, since it's nested under 2 levels and really hard to ctrl+f to find. I think we might hit a similar issue here with folks wanting to go to our docs and do
ctrl+f
then search forPDF
. I don't know the best way to solve this though :/There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since the guides were already not on the home page (anymore) I don't know if
ctrl+f
would really help in this instance.In general, I believe that most users are finding pages by searching google and getting a direct link rather than going to our docs homepage first.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yea, definitely -- but I'd like to support both flows reasonably well. Perhaps promoting search into a landing page-style box in the main content would help here. I need to think more on it.