restructuredtext

How to create a link to a header in restructuredtext?

白昼怎懂夜的黑 提交于 2019-12-02 03:14:08
问题 I have a document in restructuredtest like: Header 1 ======== and from some any other point (might be the same 'rst' file or a different one) I want to create a hyperlink to that header. So that when a user clicks on it, he gets to the page with the header Header 1 How to do that? I tried to put the following line in the other document (according to this documentation): see :ref:`Header 1` but what I get is the following: see Header 1 without any link... I also tried to follow this

Sphinx: Linking to Embedded Binary Files (PDFs)

徘徊边缘 提交于 2019-12-01 22:49:42
I'm using sphinx and RST to generate some tech documentation as HTML and having issues getting a local PDF reference to work as a hyperlink. I've seen people use :download: to link to local PDFs, but I'm embedding the PDFs inside a /docs directory for reference. I don't like :download: because it doesn't display the PDF inline in the browser which requires an extra step on the users' behalf for consumption. sphinx-build -b html does not copy any files unless they are specified in config.py hook html_static_path or html_extra_path - and even then they are dropped to the root directory or

Substitution in Admonitions

余生颓废 提交于 2019-12-01 21:43:25
How can I do a substitution in an admonition? For example: |p| account .. note:: **Been using |p| separately and now integrating?** In my sphinx conf.py I define a replacement rule which gets appended to the rst file prior to interpretation (at least that is how I understand it): rst_epilog = '.. |p| replace:: Labnext' My first substitution in the paragraph works without fail. However the substitution in the note directive isn't applied. Any work arounds? Thanks, Mike The substitution in the note works if you remove the strong emphasis (double asterisks). Nesting of inline markup is not

Divide Sphinx TOC into subsections with subheadings

人盡茶涼 提交于 2019-12-01 21:36:56
问题 I have a Sphinx master document which includes child documents as follows: .. toctree:: :maxdepth: 2 :numbered: doc1 doc2 doc3 doc4 doc5 doc6 I would like to divide the TOC into parts or subsections, so that it renders along the lines of: Part 1: Title of Part 1 <doc1 TOC> <doc2 TOC> Part 2: Title of Part 2 <doc3 TOC> <doc4 TOC> Part 3: Title of Part 3 <doc5 TOC> <doc6 TOC> My current approach is to create pseudo-child documents, that list the actual documents in their TOC, for example,

csv-table formatting in Python docstrings (Sphinx) - multiple lines in one cell

只愿长相守 提交于 2019-12-01 21:28:36
问题 I'm using Sphinx to document a Python project. There seems to be a bit of inconsistency with the .. csv-table:: directive. The main issue is a new line in a cell. And my questionable mental health. The following code: .. csv-table:: :header: Header1, Header2, Header3 A, B, "These lines appear as one line, even though they are written in two lines." C, D, "| These lines appear as two lines, | but they are indented, and my OCD will simply not allow it." E, F, "| If I continue this line in

Stop Sphinx from Hyphenating

我只是一个虾纸丫 提交于 2019-12-01 20:20:23
I have a similar question to this , except for Sphinx and RST. Namely, I would like to prevent text from being hyphenated at the end of the line. For example I want this: This is my long sent- ence. To be: This is my long sentence. How do I do this? Hyphenation is implemented by the stylesheet basic.css in the Sphinx theme "basic". div.body p, div.body dd, div.body li, div.body blockquote { -moz-hyphens: auto; -ms-hyphens: auto; -webkit-hyphens: auto; hyphens: auto; } You can override these styles with your own. See my answer to How do I customize Sphinx RtD Theme default search settings? Your

csv-table formatting in Python docstrings (Sphinx) - multiple lines in one cell

这一生的挚爱 提交于 2019-12-01 20:03:28
I'm using Sphinx to document a Python project. There seems to be a bit of inconsistency with the .. csv-table:: directive. The main issue is a new line in a cell. And my questionable mental health. The following code: .. csv-table:: :header: Header1, Header2, Header3 A, B, "These lines appear as one line, even though they are written in two lines." C, D, "| These lines appear as two lines, | but they are indented, and my OCD will simply not allow it." E, F, "| If I continue this line in another line, it will appear in a new line." G, H, "If there is a blank line between the two lines, there

reStructured Text (Sphinx) : substitution in a file name?

China☆狼群 提交于 2019-12-01 15:04:50
I want to create several files from a single template, which differ only by a variable name. For example : (file1.rst): .. |variable| replace:: 1 .. include template.rst (template.rst) : Variable |variable| ===================== Image ------- .. image:: ./images/|variable|-image.png where of course I have an image called "./images/1-image.png". The substitution of "|variable|" by "1" works well in the title, but not in the image file name, and at compilation I get : WARNING: image file not readable: ./images/|variable|-image.png How can I get reST to make the substitution in the variable name

reStructured Text (Sphinx) : substitution in a file name?

允我心安 提交于 2019-12-01 13:58:25
问题 I want to create several files from a single template, which differ only by a variable name. For example : (file1.rst): .. |variable| replace:: 1 .. include template.rst (template.rst) : Variable |variable| ===================== Image ------- .. image:: ./images/|variable|-image.png where of course I have an image called "./images/1-image.png". The substitution of "|variable|" by "1" works well in the title, but not in the image file name, and at compilation I get : WARNING: image file not

Use Sphinx autosummary recursively to generate API documentation

白昼怎懂夜的黑 提交于 2019-12-01 03:41:52
I want to use Sphinx's autosummary extension and templates to generate API docs recursively from docstrings. I want separate pages for each module, class, method, property and function. But it doesn't detect my templates at all. In fact, if I just remove the module.rst file from _templates/autosummary/ , it renders the whole file exactly the same way as before. I've followed this SO question to the letter. If you're interested, the full repository is on GitHub . Edit: It seems it does generate a different file, I had to delete docs/_autosummary for it to read the new template. However, now it