To reference a section using reStructuredText in Sphinx, I can do:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
as explained here.
This results in the section being referenced by title, that is I get the line:
It refers to the section itself, see Section to cross-reference.
(where Section to cross-reference links to the beginning of the corresponding section)
I'd like to get instead:
It refers to the section itself, see 2.1.
where 2.1 is the section's number.
Is there a way to accomplish this using reStructuredText in Sphinx?
The numsec Sphinx extension does what you want. The source code is here: https://github.com/jterrace/sphinxtr/blob/master/extensions/numsec.py.
The extension is part of the "Sphinx Thesis Resource" package developed by Stack Overflow member jterrace. See https://github.com/jterrace/sphinxtr.
Related
This works as expected
Section Header
--------------
This is a section header
Refer to section above `Section Header <#section-header>`_
But the following does not work
Refer to section below `Section Header <#section-header>`_
Section Header
--------------
This is a section below
Here is a sample to demonstrate it.
Here is the problem explained in a little more detail along with the solution
Anchor Test
===========
RST Section headers have a problem with references, refer to the `section below <#section-below>`_ that has the problem. The link does not work.
Section Below
-------------
This is a section below
The problem with the syntax section below <#section-below>_ is that the name of the section Section Below matches with the label in the external link syntax used section below <#section-below>_
I got this to work by changing the label in the external link to my section below <#section-below>_
Anchor Test
===========
RST Section headers have a problem with references, refer to the `my section below <#section-below>`_ that has the problem. The link does not work.
Section Below
-------------
This is a section below
This is the beginning of an AsciiDoc document, where the author is specified:
= Writing Documentation using AsciiDoc
Tom White <twhite#mymail.com>
v2.0, 2020-11-06
:toc:
The author name is accepted by the AsciiDoc processor, i.e. no error is produced, but it is not shown in the output document.
How is it possible to make the author's name visible?
If you are using the default Asciidoctor templates for HTML output, the author and their email address is included beneath the document heading.
If you are using a custom template, then the author and email address are available as attributes that you can use at any location within your document, {author} and {email} respectively.
For details, see: https://asciidoctor.org/docs/user-manual/#author-and-email
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 a Restructured Text document which several hierarchical sections, such as:
Main title
##########
Text under the main title.
Sub-section
===========
Text under the sub-section.
This works great, I get the correct HTML formatting when I compile it using Sphinx.
My question is: how can I go up a hierarchy level so I can add more text after a few sub-sections?
For example:
Main title
##########
Text under the main title.
Sub-section
===========
Text under the sub-section.
In my CSS, sub-section is indented.
I want this paragraph to be rendered as part of the Main title section,
not the sub-section.
I'm basically looking for a way to go up a level in the hierarchy.
Is this possible?
Thanks!
It's not possible to go "up" the hierarchy without starting a new section at the level you desire. Document section structure doesn't work that way. Changes in section level must be preceded by corresponding section titles. Using indentation to signal a section-like structure should only be used in a limited local scope.
What you're describing isn't a subsection, it's a topic. Docutils has a directive for that:
.. topic:: title
Topic text.
May include multiple body elements (paragraphs, lists, etc.).
There is also a "sidebar" directive for a similar structure, but typically for a parallel topic that's off to the side. The "rubric" directive may also be of interest.
See http://docutils.sourceforge.net/docs/ref/rst/directives.html for details.
Say I have a normal documentation part and additionally a glossar, both build in the same sphinx project.
Is there a way to link a word with let's say a headline on another page without using a normal static link?
If there is no other way than a static link, is there a possibility to introduce IDs?
You can create a link to any spot in your project using cross references. For example:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.