I work on an open source project that consists of a python API along with numerous extension modules which are installed as separate python packages. All of these extensions live in their own github repositories.
I am currently trying to improve the appearance of our documentation by using a different sphinx theme (https://sphinx-themes.org/) as well as some custom CSS I've added myself. I have now updated the core repo to use the new theme. Here are the docs for the core package.
The problem is that under our current setup I would have to make about 15 separate (but almost identical) pull requests to update the theme in all of the different repositories. Whats more any changes I do make in the future will have to be made to each individual repository. This is clearly way too laborious not an optimal way of working whatsoever.
One solution I thought about was to have the documentation theme in its own repository and have the different projects pull in the shared theme somehow. Although I'm now sure how best to execute this. Any suggestions would be appreciated.
We had the same problem when developing Trading Strategy documentation.
Eventually, we gave up finding a very good solution for this, and settle to have all documentation to a single Git repository. Any package is a git submodule dependency in this repository.
Then we have a manual script to update dependencies and make a new commit and docs build, and also the same as a Github hook in CI actions.
You could create a Python package of your theme, making sure you include its parent theme as a dependency in your requirements. sphinx-book-theme does just that.
I am trying out Sphinx for generating documentation for a Python project. Just to make sure I can actually make it work, I have made a test project to try it out on: https://github.com/ThomasA/sphinxtest.
I have run sphinx-quickstart in the root of this repository. In the following questions, I specified 'doc' as the documentation root, named the project 'sphinxtest', entered 'Thomas Arildsen' as author, answered 'y' to the 'autodoc' option, and selected the default setting for everything else.
I expected the 'autodoc' option to cause the generation of a file 'amodule.rst' in the 'doc' folder. However, this does not get generated. I am puzzled by this. I thought this was what the 'autodoc' option was supposed to do and what I have seen examples of others apparently achieve with it. Sphinx completes without any error messages, so it seems to be doing what it thinks it should do. So, what could I be doing wrong?
I am using Sphinx v. 1.5.6 and Python 3.5.3, all installed with Anaconda.
autodoc does not generate the .rst source files.
Instead first use sphinx-apidoc to generate the source files. Then run Sphinx to make your documentation.
An alternative to Percy's answer is autoapi written by Carlos Jenkins. He provides a Sphinx extension that generates the ReST files per documentation generation. You can configure the output ReST by modifying a template file.
https://github.com/carlos-jenkins/autoapi
I have written some documentation for a Python module with Sphinx. It builds and displays the HTML perfectly on my computer. However, I have been maintaining a Read the Docs version and that is not displaying properly. When I checked it when the docs were more sparse, it worked but it has since stopped.
The API page (linked) should have more methods detailed than it does. When I look at the raw .rst files on GitHub, they contain the information but it doesn't display on RTD.
I changed the folder structure for the project when I put it on PyPI, so I'm wondering whether it's that but I can't see how to fix it.
Any help would be greatly appreciated.
It turns out that I had used Requests without putting it in the requirements file. I just added it and now it builds fine.
In python I can get some rudimentary documentation for any object using help(<object>). But to be able to search the documentation, I have to go online. This isn't really helpful if I'm somewhere where the internet isn't accessible.
In R, there is a handy double question mark feature (??<topic>) that allows me to search through the documentation of all installed libraries for any function that includes <topic> in its name or documentation string. Is there anything similar for python? Perhaps even just for loaded objects?
pydoc comes with python and can do searches but only in the synopsis lines of available modules. Quoting pydoc --help:
pydoc -k
Search for a keyword in the synopsis lines of all available modules.
Note that into pydoc you can perform searches using "/".
Look in the python folder in the folder: Doc. This folder has the entire downloaded documentation of the python docs from python.org. I know this is a VERY late answer, but it brings up an easy solution.
This was mentioned in the comments already: Zeal
is similar to Dash but for Windows/Linux. It uses the same sources as Dash. It's built using Qt and is available in the repositories for several distros, for Ubuntu there is a PPA. Download it here.
Zeal is a simple offline API documentation browser inspired by Dash (OS X app), available for Linux and Windows.
Quickly search documentation using Alt+Space (or customised) hotkey to display Zeal from any place in your workspace.
Search in multiple sets of documentation at once.
Don't be dependent on your internet connection.
Integrate Zeal with Emacs, Sublime Text, or Vim. See Usage » Editor plugins for details.
It is open source (GPL), development happens on GitHub. Zeal uses the same stylesheets/HTML as the online docs, so everything should look familiar.
An in-browser alternative is devdocs.io. You can access the website even if you are offline, provided that you've marked them for local offline storage. You'll need to enable the Python 2 docs, and then mark them for offline storage here. However, as a longtime user of the online Python docs, I find the custom stylesheet that DevDocs uses a bit distracting.
Just to add another option for offline access of python docs (mostly core):
I don't have access to a linux computer at the moment, but on windows, you can navigate to your_python_dist_folder/doc to find some help files. Particularly python275.chm for instance.
If there's no doc folder on your linux machine, you can download the file here and google for a linux chm viewer:
https://www.google.com/search?q=linux+chm+viewer
::Note:
Some distributions also include docs for other packages in there... might be worth a check. Other than that, help(module) usually returns good information.
Edit:
You could get something that might be a little closer to what you want by using pydoc. E.g. you are looking for something about sin in the math module:
import math
import pydoc
[i for i in dir(math) if 'sin' in pydoc.getdoc(getattr(math,i))]
This would return the methods whose docstrings include sin:
['acos', 'acosh', 'asin', 'asinh', 'cos', 'cosh', 'isinf', 'sin', 'sinh']
for which you then could run the help() function
In case your working in a Mac there is Dash, which allows you to download docsets and then explore/search offline. Despite its documentation functionality, Dash is also a Snippet Manager.
Windows Idle - F1 from shell window or editing window gets you a windows help file of all the docs. I think it's better than the online version - it's easier to find stuff.
Although there are certainly better documentations built into your computer than help() like windows idle, another option for some of the more common topics would just be to save some of the online documentation to your computer. For the modules you use a lot and want to access offline, you could just download a text file version of the official online python documentation, which is the best place to get documentation. (file > save page as > select .txt file format)
This may not have been available at the time the question asked and answered, but python.org now makes all the documentation available online as an archive of HTML files which can be navigated and searched offline: https://docs.python.org/2/download.html
(The link directs to docs for the latest version of 2.x, but you can choose 3.x and older 2.x versions from that page)
You should try ipython.
object_name? will print all sorts of details about any object,
including docstrings, function definition lines (for call arguments)
and constructor details for classes.
The magic commands %pdoc, %pdef, %psource and %pfile will respectively print the docstring, function definition line, full source code and the complete file for any object (when they can be found). If automagic is on (it is by default), you don’t need to type the ‘%’ explicitly.
I am trying to use Sphinx to document a Python project of mine, but I am struggling with the differences between this tool and the usual tools like JavaDoc which are meant to document an API. Of course I see that Sphinx has many more uses than documenting an API, but it seems to be lacking in the simpler task.
I have managed to find out how to let Sphinx know about your package structure, so that you do not have to manually replicate it into ReST files. My next problem is:
Is it possible to include a link to the source for all classes with Sphinx?
Of course the source should be nicely formatted, but since Sphinx uses pygments I don't think that is a problem.
Take a look at sphinx.ext.viewcode.
Include a extension in conf.py.
extensions = ['sphinx.ext.viewcode']