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.
Related
PyCharm (PY-193.6911.25, macOS 10.15.4) doesn't correctly display the OpenCV documentation.
More concretely, this is the result.
As you can see, it's a mess. Is it possible to fix this? I installed OpenCV with pip.
After googling a lot I ended up thinking there is no easy solution but... there actually is!
What i did is:
Push CTRL Q
Scroll down to the trippledot and click open source.
Push CTRL+R(replace)
replace '. ' to ''
Now docstring looks like this:
Definately not perfect, but i think it looks a bit better.
Additionally i added this as external documentation:
https://opencv-python-tutroals.readthedocs.io/en/latest/search.html?q={element.name}&check_keywords=yes&area=default
So it brings up a cv2 'tutorial'...
In PyCharm 2020.1.1 professional edition with Python 3.7, the following warning is displayed for the cv2 docstring
You need configured Python 2 SDK to render Epydoc docstrings
Epydoc is a tool for generating API documentation for Python modules, based on their docstrings.
Pycharm can't render Epydoc docstrings
The suitable interpreter is looked up among those configured in the IDE (it has to be Python 2 since Epydoc package itself hasn't been ported to Python 3 yet). In other words, you need to set up it once so that it showed up on the list at Settings | Project: ... | Project Interpreter | Show All... -- it doesn't need to be actually used in any project. Is it true in your case?
The problem is that it's not really Epytext. OpenCV uses Doxygen for documentation that we don't support and also confuse with Epytext because of the similarity of tags. There is an open issue about it.
Doxygen is confused with Epydoc and displayed as free text (not preformatted)
I'm afraid this particular feature of PyCharm is not really extensible at the moment. Besides, displaying of documentation, injecting references to symbols inside it, completion of available tags and generation of documentation stubs -- everything is tied very closely to the fact that in Python code documentation is normally provided via designated string literals, not comments. The highest level API you can plug into to provide custom documentation source for Quick Documentation popup/tool window is com.intellij.lang.documentation.DocumentationProvider if you register yours before the default one with ID pythonDocumentationProvider. But it will cover only rendering, everything else will need to be written from scratch.
The official resolution is we don't support 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 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']
I'm developing an application in PyQt4 that eventually has to open and show PDF files. For this task there is a python library: python-poppler (in various spelling flavours).
The problem is that it is terribly under documented and the only simple working example I found so far uses Python+Gtk+Cairo, while the example with Python+Qt I found uses an older version of the library, and many major changes have occurred ever since, hence it doesn't work anymore.
It's a week I'm trying to use the code in the PyGtk example to hack the code of the PyQt one, but no success so far.
Has anybody got a simple example of a Python-Qt program that opens and shows a PDF file, which might be useful to the community to see how to work with that library?
Thanks a lot.
Archive with broken pyqt example
Archive with working PyGtk example
There is an example buried deep within an experimental (unused) branch of an app, here is a link to the specific file containing the code. Don't know if it'll help? All the relevant poppler code is self contained within the PdfViewer class at the bottom of that file.
http://bazaar.launchpad.net/~j-corwin/openlp/pdf/annotate/head:/openlp/plugins/presentations/lib/pdfcontroller.py
I just documented loads of my code and learnt how to use sphinx to generate the documentation. I want to include that into my GitHub project page but I do not know how to. Does anyone know existing tutorial or simple step to do so?
github will serve static content for you using their github pages feature. Essentially, you create a branch called gh-pages, into which you commit your static pages. The pages are then served at you.github.com/yourproject.
See the instructions at http://pages.github.com/.
You will likely run into an issue using Sphinx on github, because Sphinx uses directories with leading underscores. You can fix this by adding a file called .nojekyll in the the directory with the generated sphinx html.
John Paulett's answer is obviously correct and likely sufficient for most users already (+1).
Alternatively you might want to check out Ben Welsh's thorough tutorial Sphinx documentation on GitHub, which provides step by step instructions as well as a convenient Fabric based script/task tying those together to get you started to Quickly publish documentation alongside your code [...] via a single command.
github-tools has a feature doing exactly what you are asking for:
paver gh_pages_create gh_pages_build
Refer to the excellent documentation (of course using itself) for how to set it up for your project.