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).
Related
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
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 have an article document in LaTeX in which I cite sources from a bibtex file. I want to be able to still cite these sources, but I also want to be able to compile the bibliography into a separate pdf document. This document is a grant proposal for NSF, and they want the bibliography to be in a separate document.
I have searched the web for solutions to this problem. Each solution is slightly different than what I need for my particular problem.
\usepackage{cite}
\usepackage{bibentry}
...
\nocite{*}
\bibliographystyle{plain}
\bibliography{MyBibliography}
The sources are included at the end of the document, and they are labeled "References". I need them in a separate document, labeled "Bibliography".
Assuming your main file is called test, you can simply import its bibliography in a new file with \input{test.bbl} and change the \renewcommand{\refname}{Bibliography} or \renewcommand{\bibname}{Bibliography}, depending on the documentclass. This way the references will have the same numbering as in the original document.
\documentclass{article}
\usepackage{cite}
\usepackage{bibentry}
\renewcommand{\refname}{Bibliography}
\begin{document}
\input{test.bbl}
\end{document}
I am evaluating a couple different libraries to see which one will best fit what I need.
Right now I am looking at Bleve, but I am happy to use any library.
I am looking to index full files except specific ones which are in XML format. For those I only want Bleve to index specific tags as most of the tags are worthless to search. I am trying to evaluate if this is possible but, being new to Bleve, I am not sure what part I need to customize.
The documentation is very good, but I can't seem to find this answer. All I need is an explanation with keywords and steps, no code is required, I just need a push as I have spent hours spinning my wheels with google searches and I am getting no where.
There are probably many ways to approach this. Here's one.
Bleve indexes documents which are collections of key/value metadata pairs.
In your case, a document could be represented by 2 key/value pairs: name of .xml file (to uniquely identify the document) and content of the file.
type Doc struct {
Name string
Body string
}
The issue is that body is XML and Bleve doesn't support XML out-of-the-box.
A way to address it would be to pre-process XML file by stripping unwanted tags and content. You can do it using encoding/xml standard library.
For an example of a similar task you can see the code of https://github.com/blevesearch/fosdem-search/
In there they index file in custom format (https://github.com/blevesearch/fosdem-search/blob/master/fosdem.ical) by parsing it into a format they can submit to Bleve for indexing (https://github.com/blevesearch/fosdem-search/blob/master/ical.go).
Can I change the root of the treeview with a custom link instead of index.html?
Or at least add html before the treeview on the side-nav?
I think the answer is not with the vanilla Doxygen.
However, you may be able to get someway by using the '#page' documentation, which Doxygen will include before the API tree.
Doxygen also recognises '.dox' files as just containing Doxygen comment blocks - while not required for #page, these are useful where the supporting documentation is not linked to any particular source file. I've used these in the past to build the full SDK document, with background, examples, etc.
A variant is the '#mainpage', which comes first - otherwise #page entries are unordered. In the past I have modified Doxygen to order #pages by their internal name (as opposed to their title).