I've learnt that it's possible to maintain my documentation in a modular form with parts/chapters etc. across multiple files by using the include command.
The only problem with this approach is that it effectively concatenates all included files into one big file, which means that they are no longer treated as separate pages by the Sphinx Read The Docs theme.
As a consequence of this, the documentation has very long pages that users have to scroll down, rather than short pages with previous/next buttons for navigation. I would like my documentation to have the latter structure because I think that it creates a much more comfortable user experience.
How can I preserve part/chapter structure without creating a single, long, page?
Basing myself on the earlier question that you reference, I should warn you about the solution that is given there or more so about the question itself :-)
Your document did not reproduce the headings properly ("part" against "chapter") because the toctree directive considers the first heading in the included document as the "top heading" of that document. The other solution was to move the
######
Part 1
######
part in the main file, the one with the toctree directive.
######
Part 1
######
.. toctree::
:maxdepth: 2
test1
test2
I learned about this through experience. I cannot find a proper reference about this, though.
Related
I am writing lots of Sphinx/RestructuredText and this includes Sequence Diagrams using PlantUML. I have lots of text that I am reusing, so to make things cleaner, I created a definitions.iuml file. In this file, I can create named text references (via !startsub/!endsub blocks) that allows me to reference them in several different Sequence Diagrams. Change it once in the source location, and they all change. Perfect.
My problem is how to use these references outside of Sequence Diagrams? I use the exact same code (!includesub ../defintions.iuml!NAMED-REFERENCE) in the .rst file, and when I make docx/pdf, I see that link, I don't see the text that it is referencing. To make things worse, Google has like no documentation or search results on this. Queries of includesub, startsub, endsub +sphinx come back with nothing.
Help me obiwan kenobi.
I found the answer, which only resulted in more questions haha. Anyway, one thing at a time:
To create reference variables in your text document, use rst_prolog or rst_epilog in your Conf.py file. Why there are 2 commands that serve the same purpose, I dont know.
rst_prolog = """
.. |Variable1| replace:: Monday
.. |Variable2| replace:: Tuesday
"""
Now whenever you write |Variable1| in your text, the document will generate Monday.
The problem with the above is that its just for short words/phrases. You can't use it for code blocks, or anything that is more than one line. To reference in Code Blocks:
Create a new .rst file with the code you want to display. Best practice is to create a Code folder and place them all in there.
Further best practice is to stop using the '.. code block::' and instead use '.. parsed-literal::'. The output is the exact same, but parsed-literal allows you to use conf.py variables and ..codeblock:: doesn't.
So in this .rst file, first line is .. parsed-literal:: and all the text below it is the code you want to reference
In the original document that you wanted this code, type:
<4 spaces indent>.. include:: <Folder/File.rst>
Generate your document, and notice how the code is now being reference. You can include this reference all throughout your document.
I will soon be creating a new thread, this time asking how the text body and sequence diagrams can use the same reference. Currently, all text needs one reference, all sequences need another reference, and now we have double updates. Not ideal
Is it possible to get Sphinx to generate the index based on existing labels and :ref: in the text? Say if you have a label:
.. _my_label:
My Section
and later refer to it through multiple :ref:`my_label` , is there a way to get the equivalent of an automatic generation of:
.. index:: My Section
where the label is, and the same before the paragraph where the :ref: lives?
The official doc does not list labels or :ref: as index-generating markup and I could not find any extension doing it. But maybe there is one?
There's an official list of Sphinx extensions, and there are a few lists of unoffical extensions on Github but none of them implement the functionality specified in the question.
The closest approach to the problem specified in the question would be using autosectionlabel to automatically create a target label having the section name, and place an :index: or .. index:: adjacent to the reST section to place it in the index. However, this would only save having to declare the label, declaring the index entry would still be necessary.
The functionality (directive) you ask for provides little tangible gain beyond writing one less line or block of reST code (the .. index:: directive or :index: role), be it for sections or targets.
Sphinx being open source would allow implementing a custom directive for this, however using a non-standard directive having as only aim shortening standard syntax by a single construct would stand to create more difficulty than gain for readers of your source code.
I am trying to generate a hierachical documentation in Sphinx.
I would like the following structure:
Introduction
Quick start
Weather API (one general page + 2 subpages)
Temperature
Humidity
Sky API (one general page + 3 subpages)
Planets
Stars
Satellites
Future API (one page is enough for this)
Assuming that there is one file per each line in the above TOC what should I do to achieve this?
I tried to include one or more .. toctree:: directives into the top index file, but the results seem to be quite random.
Create a directory and file structure that aligns with the following toctree entries, but the actual file names are appended with the .rst suffix.
.. toctree::
introduction
quick_start
weather_api/index
weather_api/temperature
weather_api/humidity
sky_api/index
sky_api/planets
sky_api/stars
sky_api/satellites
future_api/index
We do this in a part of Pyramid's documentation, although we also globbing because the order of the files is not important. Your order appears to have importance, so listing them in your desired order is necessary.
In a Maven project with subprojects, each subproject gets an index.html with some content that comes from its POM's description element.
In one of these subprojects, I need that content to contain additional information, including links. There is a section of the doc that suggests I should not do it by trying to put HTML markup in CDATA in the description element (in fact, that doesn't work anyway; the HTML markup just comes out literal). Instead, it suggests there is some better way to get my own content included in the file.
While this element can be specified as CDATA to enable the use of HTML tags
within the description, it is discouraged to allow plain text representation.
If you need to modify the index page of the generated web site, you are able
to specify your own instead of adjusting this text.
Can anyone describe how to do that? I have tried several methods unsuccessfully (I can supply Markdown files with other names and they generate HTML, but a subproject's index.md has no effect on the generated index.html). I have also read about the custom element in site.xml but it seems to require writing a custom Velocity template for the site; I hope the passage "you are able to specify your own" must mean there is some method more straightforward than that.
Of course I would also appreciate a pointer into the docs if there is already an answer I have simply failed to find. (Just pointing me to docs I've already read isn't in itself helpful, though pointing out the answer I missed would be helpful, if it's there.)
In response to inquiries
Directory structure under src/site:
src/site
src/site/resources
src/site/resources/images
src/site/markdown
src/site/markdown/use
src/site/markdown/install
src/site/markdown/examples
src/site/markdown/build
maven-site-plugin version: 3.4
What I mean by 'adding a link':
The part of the index.html that comes from the POM description element
is the central content of the page (not the navigation bar, not the sidebar menus, but the actual content).
I would like that actual-content portion of the page to be able to have a paragraph or two explaining that this is a generated page for developers, and providing links (HTML <a href=...>) for people who arrived at the page from a web search but are really looking for the user-oriented pages.
I can't put that in the description element (even using CDATA), because HTML elements just come out literal. A comment below gives a link to a page on writing a whole custom Velocity template for the site, but is there honestly no simpler way to accomplish this?
I have the same issue. The only thing the generated index.html gives you of value is the list of modules. You can add your own index.md page to src/site/markdown, putting in whatever content you want. To reproduce the list of modules, include something like this:
###Project Modules
This project has declared the following modules:
| Name | Description |
|-|-|
|[Module1 name](module1/index.html)| Module 1 description|
|-|-|
|[Module2 name](module2/index.html)| Module 2 description|
Of course the text is not lifted from the POM. You also have to manually change this file if you have a new module. Not a perfect solution, but the best I could come up with.
Where I wrote:
I can supply Markdown files with other names and they generate HTML,
but a subproject's index.md has no effect on the generated index.html
it turns out the truth is more complex. In a project with subprojects,
there are two places such an index.md might go: in src/site/markdown/subproject-name of the parent project (where all of the other human-written docs for the whole project happen to be), or in a new src/site/markdown directory created within the subproject. A file with any other non-special name can be added in either place, and end up where you expect it in the target. But not for index.md, in that case only the second location can work, and even then, only after a clean.
I had tried both places without success, but trying the second again with a full clean install site site:stage makes it work. Out of the four combinations (parent/clean, parent/noclean, sub/clean, sub/noclean), that was the one I missed trying before posting the question, so of course that's the one that works. :)
If there had been an answer or comment like "hmm, are you sure an index.md in the subproject doesn't work, it works for me?" it probably would have put me quickly back on track. Sometimes after trying several avenues all without success, all that's needed is to know which of them is the one that's supposed to work (if indeed one of them is) and therefore worth spending more time on.
I've got a rather large asciidoc document that I translate dynamically to PDF for our developer guide. Since the doc often refers to Java classes that are documented in our developer guide we converted them into links directly in the docs e.g.:
In this block we create a new
https://www.codenameone.com/javadoc/com/codename1/ui/Form.html[Form]
named `hi`.
This works rather well for the most part and looks great in HTML as every reference to a class leads directly to its JavaDoc making the reference/guide process much simpler.
However when we generate a PDF we end up with something like this on some pages:
Normally I wouldn't mind a lot of footnotes or even repeats from a previous page. However, in this case the link to Container appears 3 times.
I could remove some of the links but I'd rather not since they make a lot of sense on the web version. Since I also have no idea where the page break will land I'd rather not do it myself.
This looks to me like a bug somewhere, if the link is the same the footnote for the link should only be generated once.
I'm fine with removing all link footnotes in the document if that is the price to pay although I'd rather be able to do this on a case by case basis so some links would remain printable
Adding these two parameters in fo-pdf.xsl remove footnotes:
<xsl:param name="ulink.footnotes" select="0"></xsl:param>
<xsl:param name="ulink.show" select="0"></xsl:param>
The first parameter disable footnotes, which triggers urls to re-appear inline.
The second parameter removes urls from the text. Links remain active and clickable.
Non-zero values toggle these parameters.
Source:
http://docbook.sourceforge.net/release/xsl/1.78.1/doc/fo/ulink.show.html
We were looking for something similar in a slightly different situation and didn't find a solution. We ended up writing a processor that just stripped away some of the links e.g. every link to the same URL within a section that started with '==='.
Not an ideal situation but as far as I know its the only way.