I would like to be able to parse sphinx based rst in Python for further processing and checking. Something like:
import sphinx
p = sphinx.parse("/path/to/file.rst")
do_something_with(p)
It seems that something is possible in docutils using the docutils.core.publish_file:
publish_file(open("/path/to/file.rst")
But that doesn't know anything about sphinx specific directives etc...
You can use Sphinx Extensions to do custom processing before the final write. There is a very good getting started example project in the documentation that discusses various hooks that allow you to customize Sphinx.
Depending on what you're trying to do, you may need to supply your do_something function as a call back argument to one of these events.
doctree-resolved(app, doctree, docname)
html-page-context(app, pagename, templatename, context, doctree)
And then you can extend sphinx as follows
def setup(app):
app.connect('doctree-resolved', do_something)
If the example in the Sphinx tutorial is not detailed enough, Doug Hellmann also has a blog post about creating a spell checker for Sphinx. I found it to be a useful reference for the Sphinx extension I had to write a while back.
Related
I have a medium-sized python project that I'm currently documenting using sphinx with the autodoc extension. I have the basics down, the generated documentation looks reasonable.
I have now come across an interesting documentation problem: I have some JSON input file that contains configuration of some sorts. It contains several sections that are used in different parts of my application. I figured the best way to keep the documentation up to date is to document configuration options as close to the point of their usage as possible.
On the other hand, I'd really like to have a single page describing the complete input file structure.
I figured it would be nice if I could somehow "transclude" the relevant documentation blocks into this page so that it shows up both in this page and within the respective module documentation pages like so:
a.py:
def fn_using_A():
'''documentation for config parameter paramA
'''
pass
b.py
def fn_using_B():
'''documentation for config parameter paramB
'''
The input file format documentation page should look somewhat like this:
paramB
------
documentation for config parameter paramB
paramA
------
documentation for config parameter paramA
I would like to not have links/references to the respective functions/modules/whatever but a verbatim copy of the documentation without having to actually copy the documentation into the respective .rst file.
It would be even better to only transclude a part of the documentation I can mark somehow within my code documentation.
I tried using reST's replace feature, writing
def fn_handling_C():
'''fn documentation
.. |paramC_documentation| replace:: foo bar baz
'''
in my code and using |paramC_documentation| within the .rst file that documents my input file format, but generating the documentation yields an error message to the effect that the replacement pattern isn't known. That doesn't surprise me since autodoc doesn't generate full .rst files for modules which are parsed together with manually written .rst files.
Is there a way to achieve this with sphinx?
I ended up writing my own sphinx extension. I used sphinx-todo as basis and modified that to my liking.
My program’s documentation is mainly written in Sphinx, but it also includes two custom HTML pages:
an example report produced by the program;
an extended reference on certain features of the program.
These two HTML files are produced by the program itself, not by Sphinx.
I want to host my docs on Read the Docs, and it would be very convenient for me to build and host the two custom pages, versioned, together with the Sphinx docs.
My program is already installed in the RtD build environment as I have the Install Project option enabled. And since the RtD docs mention writing your own builder, I gather it might be possible to invoke my program from there and have it dump the HTML content in a specific place.
So I really have two questions:
Is this an appropriate use of Read the Docs? I guess it’s not designed to host arbitrary Web pages — but then again, those files are not arbitrary, they are an important part of the docs.
How would I implement it? I’m having a hard time making sense of the RtD API: is this “builder” related in any way to Sphinx builders? how do I hook it up to RtD? perhaps there is an example somewhere?
I achieved the desired result using Sphinx’s html_extra_path feature:
A list of paths that contain extra files [...] They are copied to the output directory.
To generate these files, I haven’t found a better place than right in my conf.py, which seems a bit precarious, but works so far. Of course, Install your project inside a virtualenv needs to be enabled in Read the Docs advanced settings.
Now my custom notices.html and showcase.html are treated just like the .html pages produced by Sphinx itself, with versioning and redirects: http://httpolice.readthedocs.io/page/notices.html
I have set up a Sphinx documentation for my project and would like to extract doc strings for the source files and embed them into the final documentation. Unfortunately, the source file's language (VHDL) is not supported by Sphinx. There seems to be no Sphinx domain for VHDL.
So my ideas is as follows:
Hook into the Sphinx run and execute some Python code before Sphinx
The Python codes extracts text blocks from each source file (the top-most multi-line comment block) and assembles one reST file per source file, consisting of this comment block and some other reST markup.
All source files are listed in an index.rst, to generate the apropriate .. toctree:: directive.
The text extraction and transformation is done recursively per source code directory.
So the main question is: How to hook into Spinx?
Or should I just import and run my own configuration in conf.py?
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
from my_preprocessor import my_proc
proc = my_proc()
proc.run()
#
# Test documentation build configuration file, created by
# sphinx-quickstart on Tue May 24 11:28:20 2016.
# ....
I can't modify the build process files: Makefile and make.bat, because the real build process runs on ReadTheDocs.org. RTDs only executes conf.py.
As noted in my previous comments and mertyildiran's answer, the official way to hook into Sphinx for a language would be to create an extension to implement a new domain for VHDL.
This has already been done for many other languages - e.g. Erlang, PHP, CoffeeScript - and APIs - e.g. HTTP REST - just to name a few from sphinx-contrib. However, that is going to take a lot of time, which you don't have... You are therefore left with an option to do some quick parsing yourself and then hooking that into your Sphinx build somehow.
Since you are bypassing the official hooks, this question becomes "how do I run my own code inside a Sphinx build?" For which, I would recommend that you simply follow the guidance for a local extension - i.e. put it in a separate directory, add that to your path, then import and invoke it. As noted in the docs:
The configuration file is executed as Python code at build time (using execfile(), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file’s namespace as its configuration.
As a final though, this opens up the options to use 3rd party packages like pyVhdl2Sch (with a nod again to mertyildiran's answer) to create some schematic and then maybe write your static rst files around it to explain the schematic.
You are trying to use a sledgehammer to crack a nut.
Sphinx was originally created for the new Python documentation, and it has
excellent facilities for the documentation of Python projects, but
C/C++ is already supported as well, and it is planned to add special
support for other languages as well.
http://www.sphinx-doc.org/en/stable/
VHDL is currently not a supported language by Sphinx and because VHDL is a hardware description language its priority for becoming a supported language must be low. You have two options and first one is also my suggestion to you:
1) Use a VHDL specific documentation generator tool instead of Sphinx
VHDocL -
http://www.volkerschatz.com/hardware/vhdocl.html
A VHDL documentation utility written in Perl, based on Doxygen.
pyVhdl2Sch - http://laurentcabaret.github.io/pyVhdl2Sch/
pyVhdl2Sch is a documentation generator tool. It takes VHDL files (.vhd) as entry and generates a pdf/svg/ps/png schematic for each input file. Written in pure Python, more community friendly, more up to date.
Sigasi Studio XL Doc - http://www.sigasi.com/products/
High end edition of Sigasi Studio which is a commercial product.
2) Contribute to Sphinx project and add VHDL domain
Follow Sphinx Developer's Guide and become familiar with the project structure. Eventually add vhdl.py to this project directory: https://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains
This second option cannot be explained with a StackOverflow answer. It's up to you if you want to add more functionality to an open source project like Sphinx.
I'd like to be able to use Sphinx for the main project documentation, so the docstrings must be in reStructuredText, but I'd also like to generate HTML for reading the inline comments in the style of Pycco, which uses Markdown.
Is there a tool or combination of tools that will allow me to do convert only the docstrings from reStructuredText to Markdown?
The pyment tool can convert docstrings to different formats. You could start with that, and then write a subclass of DocToolsBase to format docstrings the way you like.
See this question What is the standard Python docstring format? for more about python docstring conventions and tooling.
A software called Pandoc may be the right tool. You can see the detail in the page through the hyperlink. I ever wanted to have try of it, but it needs Haskell runtime environment which is a little big, so I gave up.
I'd like sphinx to generate a module overview similar to the one generated by doxygen, here is an example
I can't find how sphinx can do that
I could use Graphviz to generate some sort of graph, but I can't find a way to get a clickable object in the graph that operates in the same way as the example above.
Is there any way to do that in sphinx directly or some hack to make it work as the doxygen module overview?
Sphinx has a built-in extension called sphinx.ext.inheritance_diagram that uses Graphviz. It defines one directive: inheritance-diagram. Here is an example of how you could use it in an .rst file:
.. inheritance-diagram:: mymodule.MyClass1 mymodule.MyClass2
:parts: 1
Here are some examples of inheritance diagrams in documents generated by Sphinx:
http://matplotlib.org/1.3.1/devel/documenting_mpl.html#inheritance-diagrams
http://openalea.gforge.inria.fr/doc/vplants/PlantGL/doc/_build/html/user/math.html#class-inheritance-diagram
There is also a "generic" sphinx.ext.graphviz extension for embedding graphs in documentation.