I want to write a documentation page where I have something like:
Title
*****
Introductory text
Subsection with more details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Details
Section 1
=========
Section 2
=========
Unfortunately, this only renders Subsection with more details as the main section, with all subsequent ones being the subsections. From my research, it seems to happen because Sphinx doesn't have a fixed hierarchy for headings and instead it just interprets
the document structure to decide on what the sections are, based on their succession (as seen at https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
I have also tried using upper markup to titles, to force section hierarchy, but that doesn't seem to work either.
Is there a not too invasive way of doing this? This page is for an open source project with lot of documentation pages already, not all following the same markup standards, and I'm afraid that if I tried to somehow define in our settings what each section/subsection marker should look like, we would have a lot of formatting headache ahead of us... (or I would, hehe)
=========
Section 1
=========
Thanks in advance!
Related
I need a way to escape from Sphinx’s limitation that HTML output contains one and only one page per level-1 heading. For the sake of readability, some of my document’s content must be divided into pages at a lower heading level.
I’m considering whether I can do this by manipulating the table of contents in the left sidebar, as follows.
Suppose I have a document with this structure:
Little section
A subsection
Another subsection
Big section
Level 2 in a big section
Another level 2 in a big section
Another little section
Normally the document would have three pages beginning with the headings “Little section,” “Big section,” and “Another little section.” But I want two additional pages, beginning with the headings “Level 2 in a big section” and “Level 2 in another big section.” I would do this as follows.
Put each level-2 section in a separate reST file, which makes its initial heading a level-1 heading from Sphinx’s point of view.
Add the :orphan: option to each “level 2” reST file so that it doesn’t appear in the sidebar TOC automatically.
Manually add level-2 entries to the sidebar TOC under “Big section” which have the text “Level 2 in a big section” and “Another level 2 in a big section,” and link to the orphaned “level 2” files.
I’m asking whether this is possible because I saw the following statement on sphinx-doc.org Directives page. I have put the relevant part in italics:
You can also give a “hidden” option to the [toctree] directive, like
this:
.. toctree::
:hidden:
doc_1
doc_2
This will still notify Sphinx of the document hierarchy, but not
insert links into the document at the location of the directive –
this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.
This appears to say: Yes, what I propose is possible. But I can’t find a clue to how it’s done. Can anyone provide insight?
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
Reading through GitHub's help website, I've come across a very neat-looking procedure list.
From GitHub's Create A Repo Tutorial
I have read through GitHub's Markdown Tutorial as well as the Markdown Cheatsheet, but have not found any way to perfectly replicate this type of format.
The closest I have done so far was to basically put a blockquote after a number list entry:
1. > line 1
>
> line 2
2. > line 3
>
> line 4
And it looks similar, but, well, see for yourself:
Is this the closest I can get to GitHub's format?
Is there a proper Markdown syntax that I have missed?
If not, is there a way to achieve this in raw HTML?
If you look at the source of that page you can see that this is just a normal ordered list containing paragraphs:
<ol>
<li><p>In the upper-right corner of any page, click...
So to produce that HTML with markdown simply use the normal ordered list syntax:
1. First paragraph here.
2. Another paragraph here.
The particular appearance of that page is done by styling with CSS. It looks a little involved, using the ::before pseudo-element. If you want to replicate something similar have a look at the page with your browsers inspector to see the the styles. Experiment until you understand how it works and can create the effect you want.
If you are looking to create this effect on your own Github pages (e.g. a README) then I think you are out of luck, since you can’t control the CSS.
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`.