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.
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 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.
I was looking for a quick way to autoformat/pretty-print JSON in Vim the other day and found this great little command on Stack Overflow: :%!python -m json.tool
That sent me on a search for a list of other Python tools to pretty-print common web files, but I couldn't find much. Is there a good resource/list of Python tools that they find particularly useful for cleaning up poorly formatted web stuff inside Vim (e.g. HTML, XML, JavaScript, etc.)?
Python
Are you just looking for a resource for Python one-liners? You could browse through the Python standard library documentation to find more inspiration.
Or simply google "python one-liners json.tool" to find additional resources. For example, this Reddit post: Suggestion for a Python blogger: figure out what what all the stdlib main functionality is, and document it
Command line
Vim supports more than just Python (e.g. HTML Tidy as Keith suggested). Any tool that can accept pipe/standard input will integrate well with Vim.
The % command just picks a range that contains the entire file, and ! filters that range through an external program.
See :help :% and :help :!
For XHTML and XML files you can use tidy.
:%!tidy -i -asxhtml -utf8
:`<,`>!tidy -i -xml -utf8
The last one works on visual selections.
Vim has a command to do it, = (equal), like in ggvG= will reindent the whole file. Try :help = for more info about how to use functions and external programs with =. The default configuration uses internal indenting rules which works for most file types.
There are loads of good tools that are can convert text between the two formats:
par: for hard line wrapping.
pandoc: for HTML, LaTeX, rst, and Markdown
autopep8: for parsing Python code into an AST and spitting it out as pep8 compliant.
...
Vim is designed to make use of such utilities by the powerful formatprg settings. That by default is mapped to the gq operator. It works well with Vim motions, Vim text objects, selections, etc.
For instance, I use the setting below for on my Python files
au FileType python setlocal formatprg=autopep8\ --indent-size\ 0\ -
John MacFarlne has a good article about creating a specialised script using pandoc which you could stick in your vimrc.
!autopep8 -i % seems to work fine in vim . The -i switch is to over-write the existing file in place. Use more # autopep8 --help.
There is a vim plugin for this if you really are thinking of being a power user. Outside of vim you can test it with autopep8 -diff {filename} or autopep8 {filename}.
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.
I'm interested in using Python to hack on the data in Flash swf files. There is good documentation available on the format of swf files, and I am considering writing my own Python lib to parse that data out using the standard Python struct lib.
Does anybody know of a Python project that already does this? I would also be interested in any available solutions that use Perl, Ruby, Haskell, etc.
Well, unless you're doing it for fun (in which case, go for it!), why not use Ming? It supposedly has python wrappers...
I found another option in SWF Tools. They provide a Python wrapper that supports generating SWF files in Python.
I'm not sure if either SWF Tools or Ming actually supports parsing in and modifying an existing swf file, however. Both seem geared more towards generating swf files from scratch.