Sphinx has this meta directive but it need to be be added manually in each RST document.
.. meta::
:description: The Sphinx documentation builder
:keywords: Sphinx, documentation, builder
I would like to set meta description using conf.py in one global config file.
There is an extension sphinxext-opengraph with option to return description text with configurable amount of characters taken for the page using ogp_description_length
I wonder if it can be used to achieve this for meta description.
Thanks in advance.
Related
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
To customize a certain page in my documentation, I'd like to add a special class or id to the body of the page.
I've tried using
:name: amazing-unique-id;
at the top of my index.rst file, but this doesn't work. Any idea how I could achieve that?
I'm writing documentation in RST format and generating HTML using Sphinx.
I want to be able to write a paragraph in an RST file and reuse the same paragraph in a different RST file in the same folder. I want the reuse such that if I make a change in the original paragraph it should automatically change in all other files it has been referenced when i generate the HTML using Sphinx.
Is there any RST syntax to make this happen? Any help is appreciated.
You can use the include directive.
For a basic include, reference the paragraph you want to reuse as follows:
Some text
.. include:: /path/to/file_to_include.rst
More text
In our example, the content of file_to_include.rst is Included text.
Sphinx will generate:
Some text
Included text
More text
As you can see in the docutils documentation (linked above), you can optionally specify a set of options, for example to restrict the included text to a range of lines.
I have just recently (yesterday) started using sphinx and read the docs for my project.
Till now I am happy with the Html documentation but the pdf version includes all the articles That appear in the index within the Contents heading. And the Documents orignal content/index is simply comprised of two links.
Please help.
The documentation is at http://todx.rtfd.io and the pdf is here.
When generating the PDF, Sphinx is always adding the content that is referenced via a .. toctree:: directive exactly where the directive is placed.
In contrast, when generating HTML, Sphinx is placing the content after the file that contains the toctree.
In this aspect, PDF generation and HTML generation are simply inconsistent.
Thus, you should place all content of the index page before the table of contents.
In case you want to provide an overview of the most important sections inline, you can use a list of references. Then, you might want to hide the toctree using the hidden property, for example like this:
Contents
--------
- :ref:`quickstart`
- :ref:`userguide`
Features
--------
- Fast
- Simple
- Inituitive
- Easy to Use
- Offline
- Open Source
.. toctree::
:hidden:
quickstart
userguide
I have reStructuredText file for Sphinx documentation similar to this:
Page Title
==========
**Contents**
.. contents::
:local:
:backlinks: none
----
Subtitle |mongodb_icon| |postgre_icon|
--------------------------------------
Some totally irrelevant text here...
(|mongodb_icon| and |postgre_icon| substitutions are defined in rst_prolog in conf.py)
Is it possible to render out the Subtitle in Contents without |mongodb_icon| |postgre_icon| part somehow? I'd like to have different strings for 'contents' section and for the title itself, especially because in this way, generated URLs also include that text which I would like to avoid (e.g. _build/html/docs/page.html#subtitle-mongodb-icon-postgres-icon).