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.
Related
I' writing a new extension for Sphinx as a domain offering multiple directives, roles and indices for the hardware description language VHDL. This extension shall be able to auto document language constructs. In VHDL, we have e.g. entities/architectures or packages/package bodies. These could be documented as pairs in individual docutils documents, so each language construct has an individual URL (or page in PDF) in the documentation.
I'm looking for a solution to create new documents in Sphinx/docutils. According to the docutils API description, a document is the root element to a doctree (documentation tree). According to the Sphinx documentation, directives are items in the doctree that get consumed and can emit new nodes to the surrounding doctree. So it's a translation/replacement approach.
Non of the documentation seams to offer a way to create new document.
Looking at the autodoc extensions, there are 2 sides. There is sphinx.ext.autodoc coming with Sphinx. It offers .. auto*** directives to automatically document Python language constructs. It requires a user to place dozens to hundreds of auto-directives into the ReStructured Text. Of cause it automatically document e.g. classes or modules, but for a huge project it's a lot of work.
In addition, there is autoapi, which reads the Python code for a given package or module and generates ReST files on the fly when Sphinx is loaded. Then these files - containing auto-directives - are processed.
As I understand, autoapi workaround the problem of creating now docutils documents, by writing ReST files, so Sphinx generates document instances with a doctree, and then autodoc from Sphinx jumps in and replaces them with content from doc-strings.
So my questions after all investigations I did so far:
How can I create docutils or Sphinx document to get a HTML file per item I want to auto document?
Or do I always need to do a hack like autoapi from Carlos Jenkins and create ReST files as dummies or with auto directives, so I can use the replacement capabilities of Sphinx/autodoc from directive to documentation nodes?
Why don't I like the autoapi approach? I have parse VHDL files as input in form of a Code Document Object Model (CodeDOM). I don't want to serialize parse VHDL file into ReST, to parse it again, construct again a model of my source files, so I can then translate to documentation nodes like sections, paragraphs and lists.
I have all available to generate doc-nodes for docutils, but I need multiple documents, so I can distribute the content to hundreds of documentations file (HTML files).
I see a lot of examples like
:ref:`code <target to code>`
in the Sphinx documentation, but I can't find where it defines what code and <target to code> mean. Perhaps one of them is an implicit or explicit target and the other is the path to a file??
If someone can give me examples of how to cross reference a title in a specific .rst file?
From Adding a cross-reference to a subheading or anchor in another page I know how to use the :any role, but not how to do a :ref: to a specific file.
From the documentation for Cross-referencing syntax:
Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write
:role:`target`
and a link will be created to the item named target of the type indicated by role. The link’s text will be the same as target.
There are some additional facilities, however, that make cross-referencing roles more versatile:
You may supply an explicit title and reference target, like in reST direct hyperlinks:
:role:`title <target>`
will refer to target, but the link text will be title.
Note that sometimes title is also called label, depending on context.
I have a couple of examples (all with titles) and I'd like to create an index/list out of them automatically.
An example can be seen in the chunked AsciiDoc User Guide table of contents (or beneath):
The asciidoc source of the AsciiDoc User Guide does not show anything specific to me for Asciidoc itself, I could find the following hint to Docbook:
DocBook toolchains will normally automatically number examples and generate a 'List of Examples' backmatter section.
I'm looking for the (asciidoctor?) standard html5 rendering, but I'm open for different suggestions.
Adding the :doctype: book attribute alone does not do it. So I merely hit dead ends not knowing if it is possible at all. Also I'm new to Asciidoc so I might just miss some pointers, too.
The Python Asciidoc repo includes the a2x tool, which is a wrapper around a DocBook toolchain. It is DocBook that is producing these entries in the table of contents. Neither Python Asciidoc, nor asciidoctor, can do this out of the box.
You would need to curate the lists manually, or create a macro that does the curation for you. This thread might prove helpful: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/111
In markdown I can write:
[example1][myid]
[example2][myid]
[myid]: http://example.com
so I don't have to retype the full external link multiple times.
Is there an analogous feature in AsciiDoc? Specially interested in the Asciidoctor implementation.
So far I could only find:
internal cross references with <<>>
I think I saw a replacement feature of type :myid:, but I can't find it anymore. And I didn't see how to use different texts for each link however.
Probably you mean something like this:
Userguide Chapter 28.1. Setting configuration entries
...
Attribute entries promote clarity and eliminate repetition
URLs and file names in AsciiDoc3 macros are often quite long — they break paragraph flow and readability suffers. The problem is compounded by redundancy if the same name is used repeatedly. Attribute entries can be used to make your documents easier to read and write, here are some examples:
:1: http://freshmeat.net/projects/asciidoc3/
:homepage: http://asciidoc3.org[AsciiDoc3 home page]
:new: image:./images/smallnew.png[]
:footnote1: footnote:[A meaningless latin term]
Using previously defined attributes: See the {1}[Freshmeat summary]
or the {homepage} for something new {new}. Lorem ispum {footnote1}.
...
BTW, there is a 100% Python3 port available now: https://asciidoc3.org
I think you are looking for this (and both will work just fine),
https://www.google.com[Google]
or
link: https://google.com[Google]
Reference:
Ascii Doc User Manual Link
Update #1: Use of link along with variables in asciidoc
Declare variable
:url: https://www.google.com
Use variable feature using format mentioned above
Using ' Link with label '
{url}[Google]
Using a relative link
link:{url}[Google]
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.