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?
Related
Looking at the CERT Secure Standards (Example: https://www.securecoding.cert.org), there are specific standards, with great examples of what good and bad code looks like, for C, C++, Java, even Perl but not Python. Are there any Python specific standards are guidelines, preferably with examples available?
http://www.pythonsecurity.org/ appears to be focused security concerns in Python itself and on building an alternative Python binary to resolve these. A noble, but not recently active, cause. I'm looking for something that gives guidance to developers on what not to do and what to do instead.
Seeing as lot of people are recommending formatting guidelines (PEP8), I have one that is actually for security.
There is a project in OpenStack (very big python based platform), called Bandit. It is a security lint tool.
https://github.com/PyCQA/bandit
You can run this tool against your own code, or if you wish to learn the inners of secure python coding, then take a look at the examples directory.
One place to look at a secure coding standard is
https://vulncat.fortify.com/en
There you have listed coding errors that affect security. It contains many languages, Python being one of those.
I have also been looking for an academic/free secure coding standard for Python. I haven't yet found a good one. I think that SEI CERT should step up and make such a standard. According to their latest webinar on Secure Coding, they are considering this possibility.
I would recommend using a text editor with a code linter for PEP8, or attempting to learn the PEP8 guidelines themselves. PEP8 lists the style recommendations for Python programmers and is quite comprehensive, which has then been adopted into plugins or directly into editors to ensure code meets these style guidelines.
Python is wonderful in that there are many available code linters, those that recommend proper style based on PEP8.
Great examples of this include Sublime Text with PyLinter or Flake8, or PyCharm without plugins (both freemium, fully-fledged for free use).
I would personally recommend Flake8 or PyCharm over PyLinter if you like to have some "creative liberty", as PyLinter is quite strict.
I posted this in another thread, but we recently released a security linter called DevSkim for Visual Studio, VS Code, and Sublime Text. It targets multiple languages, and is focused on finding security vulnerabilities.
CERT was developing a Python Secure Coding standard - but nothing seems to have come from their efforts for a number of years.
https://wiki.sei.cmu.edu/confluence/display/seccode
Several CERT folks state in presentations that the Python Secure Coding v1.0 is "under development".
You can refer to my blogpost for coding guidelines in python. You need to follow PEP8 coding guidelines. Autopep8 is a tool that automatically formats Python code to conform to the PEP 8 style guide. To run autopep8:
autopep8 TARGET.py
So, I've released a small library on pypi, more as an exercise (to "see how it's done") than anything else.
I've uploaded the documentation on readthedocs, and I have a test suite in my git repo.
Since I figure anyone who might be interested in running the test will probably just clone the repo, and the doc is already available online, I decided not to include the doc and test directories in the released package, and I was just wondering if that was the "right" thing to do.
I know answers to this question will be rather subjective, but I felt it was a good place to ask in order to get a sense of what the community considers to be the best practice.
It is not required but recommended to include documentation as well as unit tests into the package.
Regarding documentation:
Old-fashioned or better to say old-school source releases of open source software contain documentation, this is a (de facto?) standard (have a look at GNU software, for example). Documentation is part of the code and should be part of the release, simply because once you download the source release you are independent. Ever been in the situation where you've been on a train somewhere, where you needed to have a quick look into the documentation of module X but didn't have internet access? And then you relievedly realized that the docs are already there, locally.
Another important point in this regard is that the documentation that you bundle together with the code for sure applies to the code version. Code and docs are in sync.
One more thing especially regarding Python: you can write your docs using Sphinx and then build beautiful HTML output based on the documentation source in the process of installing the package. I have seen various Python packages doing exactly this.
Regarding tests:
Imagine the tests are bundled in the source release and are easy to be run by the user (you should document how to do this). Then, if the user observes a problem with your code which is not so easy to track down, he can simply run the unit tests in his environment and see if at least those are passing. If not, you've probably made a wrong assumption when specifying the behavior of your code, which is good to know about. What I want to say is: it can be very good for you as a developer if you make it very simple for the user to execute unit tests.
I'm packaging my new python library for PyPi. The repository contains:
Sphinx documentation sources
Supplemental JavaScript library
Examples
Is it a good idea to include such things into a python egg?
What's the convention?
You can see the guts of the library at https://github.com/peterhudec/authomatic
You shall not make everything into the python egg, but anyway, that's up to the python setup.py bdist_egg to choose what to include or not. But in the source package you upload to pypi, yes, include everything that can't be generated by setup.py. You can upload separately the documentation, so it can get published as well.
But generally, what you need to get included in the egg, is what is necessary for the egg to run as-is. Everything else can be included, but can be distributed through other ways, that's up to you.
There are packages on PyPI that are entirey (or almost) entirely written in bash (virtualenvwrapper.sh is one).
If there is a supplemental JavaScript library that you can package, that wouldn't be a bad thing. This prevents the case where the user might not have npm installed, so it makes your library easier to use and your users happier.
Documentation doesn't NEED to be included but if you want to, then by all means do it. Libraries both include and don't include documentation. github3.py now includes it while requests does not. It's up to your preference.
I personally always have the examples in the documentation, so they're included in my packages that include the documentation. I can't think of any packages off the top of my head that include a separate package of examples, but if you feel it's necessary, then go ahead. I might, however, make that a sub-directory of the library itself though. It will make the name-spacing better when it is installed.
But basically, there are no set conventions beyond having the code to perform the task you say the package will perform.
What I can tell for PyQT4:
it includes doc, examples, plugins, ...
I do not know about your JavaScript library but I think it is no problem to include that as well.
This is an example - I do not know the convention. I would put in everything that could be important to the user of your library.
I am trying to use VTK from python. I tried to find and could not realy find anything on the web which can be used for documentation. I tried looking at the c++ documentation but the methods are very different.
Thanks a lot
You could see the python examples at VTK's wiki. There is another resource by going to the official nightly documentation and looking for a particular class; in the section examples for many (not all) classes you can find implementations in python (also in c++ and tcl). A third option is to go to the source folder of your last downloaded release of VTK; look for the folder "Examples", there you will also find different VTK implementations in python (besides C++ and tcl)
I recommend you use Mayavi and TVTK from Enthought, the API is much pythonic:
http://code.enthought.com/projects/mayavi/
On the VTK website you can find the VTK User's Guide. It is pretty thorough.
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.