VSCode can't render simple or grid-based reStructured tables in docstrings. It only understands GFM tables. However neither Napoleon nor MyST provide a way to parse them. MyST has a Python API, but I couldn't find out any way to hook a Sphinx event to one of those functions.
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 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
I'm trying to use Sphinx to auto-generate API documentation for a Python library, and I can't make it properly format the example code snippets in the docstrings - they do get indented but lines of the same indentation get concatenated (https://weka-io.github.io/easypy)
I understand that the problem is that the format I'm using to mark the code blocks is Markdown (indent them by 4 spaces) but Sphinx is expecting reStructuredText (code-block::)
I've tried googling for a solution and it recommended using recommonmark - but it seems to be for using .md files as the source. I'm using sphinx-apidoc to generate the "source" .rst files from the Python code - so it's not going to work (unless there is a way to make sphinx-apidoc generate .md files instead)
So - how do I make Sphinx treat just the Python docstrings as Markdown, leaving the elaborate reStructuredText framework as is for everything else?
I really like a lot of the features of Sphinx, but I also require the final output to be docx. I've had great luck with .rst -> .odt -> .docx using rst2odt.py (docutils) and LibreOffice. I noticed that Sphinx can generate "Docutils XML". In my mind, I should be able to use that and then go to .odt through the same mechanism as rst2odt.py does. However, I'm not sure how I would go about that. I realize that there is a package sphinxcontrib-docxbuilder, but it uses python-docx internally which has rather limited table support based on my experiments. I am using rst specifically because of the ability to do column/row spanning in a very clean way.
The alternative that I'm currently considering is to use something like jinja2 to do all the stuff I would need Sphinx for and stick stick with rst2odt.py.
I am using asciid for an article. In the end of my document I want to have a list of figures. How to I create a list of figures? Did not find something useful in the documentation for me.
Nope there isn't one at the time of answer. I checked the docs (which you indicated you did as well) and I also grepped the codebase. There is good news though! You should be able to do this with an extension.
Extensions can be written in any JVM language if you're using asciidoctorj, or in Ruby if you're using the core asciidoctor (I'm not sure about JavaScript for asciidoctorjs). You'll need to create two extensions probably: a TreeProcessor extension to go through the whole AST looking for images and pulling them out into a storage structure. Then you'll also need to create either an inline or block macro to actually place it within the page.
I strongly recommend examining the API for the nodes and functions you'll want to make use of. There are some other examples of processors that may also be helpful to examine.