Created using Sphinx 0.6.5.
I know Python's documentation uses reStructuredText, but it has different sections like http://docs.python.org/whatsnew/2.6.html and http://docs.python.org/tutorial/index.html.
How do you do this in reStructuredText? Do you run rst2html in a bunch of directories, keeping its structure?
I know that it uses Sphinx (not rst2html directly as said by Thomas Wouters in an answer), but how you should organize your rst structure with source code files in a repository so you have a full blown automated doc website?
The Python documentation uses reST for its markup, but it generates the HTML using sphinx, not rst2html directly. The sphinx tool is what converts all the individual .rst files into multiple .html files. To see how the Python docs are generated, see http://svn.python.org/projects/python/trunk/Doc/Makefile
I found the sampledoc tutorial on the matplotlib site quite useful to get started with Sphinx.
Here is how to build Python documentation exactly.
Related
The package I want to document with Sphinx contains pure Python modules (ok) + a C/C++ library bind using pybind11.
There are a lot of dependencies that can not reasonnably be built on ReadTheDocs!
So on RTD, autodoc can not import my library to extract the docstrings...
My first idea was to generate _build/doctrees locally and use it on RTD. But it contains binary files, heavy to store in the repository: no.
Is there a way to "expand" autodoc directives in RST files? It could produce full text of RST files or a fake static module as a .py...
Thanks in advance for your ideas!
Mathieu
I think there are two potential ways to grab the docstrings from C/C++ compiled libraries:
Option 1
Install all the system dependencies to install/build the Python packages you need. This can be achieved on Read the Docs by using the key build.apt_packages in the config file (see https://docs.readthedocs.io/en/stable/config-file/v2.html)
Option 2
Try using sphhinx-autoapi extension (https://sphinx-autoapi.readthedocs.io/en/latest/) instead autodoc. This extension does not require to have the dependencies installed since it works statically by parsing the files directly instead of inspecting them dynamically.
I wrote a small tool that produces Python code from a compiled Python extension (signatures and docstrings of course).
In the case, it can be useful for others:
https://gitlab.com/doc-tools/pydoc-codedoc
(still incomplete of course)
I am working on using ctypes in various languages. I would like to look at the sourcecode of the crypes library in python in a text editor. Specifically I was looking helper functions of memmove, memset, string_at, wstring_at. Based on that implementation I'll recreate the helper functions in my other languages.
I searched and came across these links here:
http://sourceforge.net/project/showfiles.php?group_id=71702
http://starship.python.net/crew/theller/ctypes/old/index.html
But none of them have the library in text format so I can't view it. Can you please share with me link to like the github or hg repo where I can view the libraries code.
CTYPES can be found in the official mercurial repository for the source code of the Python language, in the appropriate folder. It can be seem through the web at this URL:
http://hg.python.org/cpython/file/3134189655b1/Modules/_ctypes
I really like readthedocs and I'm using it in my python projects.
I've got a repo containing only latex files and was wondering if readthedocs is able to compile it to pdf or if there are other services who could do this.
According to this link to readthedocs docs, they use Sphinx as generator, which can generate PDF from reStructuredText (reST) within LaTeX output. As far as I know, the answer to your question is no, readthedocs cannot generate pdf from a repo of LaTeX files, regarless of all output format they have (including PDF), because Sphinx use reST as input format.
I don't know much about readthedocs (besides the quick search I made for this response), but you could try Latex Online for your purpose if your repo is a Git one. Also, if you want to collaborate on and/or edit TeX files online, take a look at ShareLaTeX. Both are OSS and can be installed via Docker.
On my Linux computer, I have built scipy from source via the command
python setup.py build_sphinx
what has generated a bunch of rst files in the scipy/doc/source/generated folder.
But how do I access this documentation? Do I have to generate html files before?
reStructuredText is intended to be (mostly) readable as source, but it is probably best rendered as HTML for human eyes using docutils.
There seems to be a plethora of documentation tools for Python. Another one that I've run across is epydoc. It seems like Sphinx is the de facto standard, because it's used to generate the official Python docs. Can someone please sort out the current state of Python's documentation tools for me?
epydoc and Sphinx are different types of tools.
They are the same in that they:
Both use ReST via docutils.
Both are very Pythonic in their focus
Both can generate HTML and PDF documentation
They are different in their focus.
Epydoc is focused on API (Developer) documentation. You get more results quicker with Epydoc. You point it at your source code and you get something. This is what I want from an API documentation tool.
Sphinx is focused on general (User) documentation. While Sphinx does pull a lot of information from your source code you need to put a little more into it. Sphinx can generate API documentation but, it's not as straight forward, and IMO doesn't do as good of a job as Epydoc. I know some will disagree because Sphinx is chosen for Python. BUT, it depends on how much work you want to put into it. I do love Sphinx for general documentation.
So it depends on how much work you want to put into it and what you are documenting.
I recently changed from Python2 to Python3 and found that there was no Epydoc package for Python3. So it seems with Python3 there is a clear focus on using Sphinx as API documentation.
It seems like Epydoc is, if not dead, at least pining for the fjords.
Sphynx with the sphinx-apidoc command and the autodoc extension looks to be the most popular option for API docs at this time.
Good examples are:
requests (src)
boto (src)
See: Should we use Epydoc, Sphinx or something else for documenting Python APIs? (SO5579198)
Sphinx encourages a more narrative style than tools in the javadoc mold, but maybe this is a good thing?