Is there a simple way (i.e., without creating an entirely new theme) to customize Sphinx so that it generates HTML pages without the search box?
An alternative, which I discovered reading the alabaster theme documentation is to explicitly list which (if any sidebars) are desired in the conf.py file. For example, including this fragment in conf.py:
html_theme = 'alabaster'
html_sidebars = {
'**': [
'about.html',
'navigation.html',
'searchbox.html',
]
}
produces the searchbox; removing searchbox.html from that list and then building produces the same page but without the box. (More information can be found at the Sphinx documentation for the build-configuration file.)
You can do it by customizing (or should I say disabling) the searchbox template.
In conf.py, add this line:
templates_path = ["templates"]
Create a folder called templates in your Sphinx project directory.
In that folder, add an empty file called searchbox.html. This overrides the default template file (located in sphinx/themes/basic where Sphinx is installed).
Related
I am in process documenting my python library. I would like to add custom icons. I see I can add font awesome icons. However, I must not be googling very well or...
Is it possible to add custom icons to Sphinx(-rtd-theme)? If so, is there an example? I cannot find one. Thank you.
The closest thing I found was the sphinx-design package then using the avatars class with the {div} directive (Myst). e.g.:
:::{div}
<img src="images/whale_trace.png" class="sd-avatar-md sd-border-1">
:::
note: i use .md instead of .rst. Thus, I use the Myst parser. In order to copy the image over and use the right path, the conf.py file needs to be modified :
myst_enable_extensions = ["colon_fence", "html_image"]
adding html_image will all resolution of the image. See Myst documentation:
> Blockquote
HTML parsing to the rescue!
By adding "html_image" to myst_enable_extensions (in the sphinx conf.py configuration file), MySt-Parser will attempt to convert any isolated img tags (i.e. not wrapped in any other HTML) to the internal representation used in sphinx.
_
I'm using Sphinx in a project and I wanna change 'See also' title in top of the seealso::'s box in the template.
I also searched a little in the codes and saw the SeeAlso class in the Sphinx library but I have no idea how to override it and change the title.
Well, I finally found a way that I think is the simple one!
My question was to be able to change the title of sphinx specific admonitions like seealso::
In the locale folder (sphinx/locale/__init__.py) , there is a dictionary named admonitionlabels, that the titles are defined here.
To change it in the project, we just add this code in the project's config.py:
from sphinx import locale
locale.admonitionlabels['seealso'] = 'new title'
and when we use make html sphinx will apply our new title to the project
While using the basic theme, I have noticed that Sphinx (v3.2.1) seems to be generating "Next/Previous topic" sections. Is there any simple way to remove those?
Add the html_sidebars option to your conf.py file and pick the elements that you want in the sidebar. This overrides the theme's default sidebar elements. You can also add custom HTML elements to the _templates directory and include them in the sidebar, as well as customize what the sidebar displays on different pages. See the Sphinx docs for more info on the sidebar elements Sphinx provides by default.
Obviously this differs between themes since not all of them include rellinks in the sidebar, but for the out-of-the-box theme this should remove the previous/next topic links and display on the TOC and search box.
html_sidebars = {
'**': ['globaltoc.html', 'searchbox.html']
}
Using Sphinx documentation generator (with pdflatex), I am creating pdf files and have added links to some of the internal files using label and ref markups like this:
In the called file (xyz.rst)
.. _called-file-label:
In the calling file(abc.rst) I am adding a reference to the label like this:
:ref:`Get Info <called-file-label>`
With the above arrangement, I am able to generate pdf file using pdflatex. However, I find that the called file is also added to the pdf file's bookmarks section which feels somewhat clumsy.
I understand I need to add both the source files in the .. toctree:: section for the hyperlink to appear in the pdf file (I have added the called file using :hidden: directive to prevent the file from showing up in the html document's ToC tree).
My question is: What do I need to do in order that the called file (xyz.rst) does not figure in the bookmarks section of the generated pdf file?
If after .. _called-file-label: label is section:
.. _called-file-label:
Foo Bar
======
Then, the section title "Foo Bar" will always become a bookmark in PDF.
The :hidden: option of toctree is not to hide documents, but to don't show ToC on the place with toctree. I.e. it is to hide toctree, not its documents. Documents in hidden toctree will still be visible in HTML sidebars, PDF bookmarks, etc.
It looks like you need rubric directive. Rubric is like a section, but doesn't make up the table of contents.
I'm generating html documentation in Sphinx.
How do I modify the sidebar for each of the html pages in my document so that they include the toctree? By default the toctree only seems to display in the master_doc page, and only in the main area instead of the sidebar.
Is there an easy way to do this? I'll be using readthedocs to host the generated documentation, so I would prefer to avoid the use of any third-party plugins, unless they are also available on readthedocs.
You can customize your html sidebar in conf.py.
The default html sidebar consists of 4 templates:
['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']
In conf.py you could change localtoc.html to globaltoc.html like this:
html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }
Since this in the end this will be used in HTML files, this should work on ReadTheDocs.
Including the 'globaltoc.html' has a drawback in that it doesn't show both the global and local toc for the page you're viewing.
It appears that others were irked about this limitation and resulted in the subsequent development of an extension to support a full toc in the sidebar, checkout: https://pypi.python.org/pypi/sphinxcontrib-fulltoc
Nothing will appear in the "Navigation" section of the default Sphinx sidebar until you add the names of files that you want to scan for section headings to the toctree:: directive in your .rst file.
For example, if you want all the headings of your index.rst file to appear in the Navigation pane, write index (without the extension) in the toctree:: list like so:
My Level 1 Heading
==================
Glorious content.
My Level 2 Heading
------------------
More content
.. toctree::
:maxdepth: 2
:caption: Contents:
index
The crucial bit is adding index right there at the end. If you're like me, you start your projects with the auto-generated template from sphinx-quickstart, which (at time of writing) populates your .rst files with EMPTY toctrees.