Another way to ask this:
If I wrote doctests in reST, can I use it for Sphinx or other automatic documentation efforts?
Background: I don't know how to use Sphinx and have not much experience with reST either, so I am wondering if I can use reST-written doctests somewhere else useful than with Sphinx?
Why would I write doctests in restructured text?
You don't really write the tests "in restructured text". The interactive examples are the test cases, and it does not matter what the surrounding markup looks like; it could be reST, or it could be something else like Markdown or LaTeX.
reST has been adopted as the "official" markup language for Python documentation, but you are not obligated to use it.
so why is the simple usage example for doctest.testfile() from the doctest documentation then given as a reST file?
Doctest is a way to test code by checking the correctness of embedded interactive examples in documentation, so it makes sense that examples explaining the doctest module also include reST markup.
You can run doctest on text files that contain only interactive input/output examples, and no other content. Those examples could be useful as lightweight unit tests, but on their own they would be less suitable as documentation.
I am wondering if I can use reST-written doctests somewhere else useful than with Sphinx?
Having testable code examples can be useful even if you don't use Sphinx for your documentation.
If you are looking for alternative documentation tools that understand reST, take a look at docutils (which Sphinx is based on, btw) and its front-end tools, such as rst2html.py.
Another tool that might be of interest is rst2pdf.
Adding doctests to your documentation makes sense to ensure that code in your documentation is actually working as expected. So, you're testing your documentation. For general code-testing, using doctests can't be recommended at all.
Related
I would like to provide code snippets to show-case how one could use a particular method or class in python. How can I do that?
In Java one could use <pre> ... </pre> to do so.
Doctest is the only way?
As I look at the existing docstrings for typical packages (e.g., pandas, numpy, etc), I never see anything other than doctest which is intended to test the method and not just to format text as python code. So, if doctest is the only way, what would be the proper way of formatting a snippet of code to look like interactive python sessions? I don't want to write my code in an interactive session each time and then c+p it in my docstring. It doesn't seem to be right.
DocStrings are not the only way. If you are using Sphinx to generate documentation then you should read this.
Example
Here is something I want to talk about:: <-- Special syntax to mark code beginning
def my_fn(foo, bar=True): # Code itself
"""A really useful function.
Returns None
"""
For example, when i use matplotlib as plt, a possible statement is like below:
plt.plot(x,y,color='blue')
so how can i get what arguments like 'color' i can pass to the 'plot' function, and what is the proper values for that argument?
Especially when i use some modules.
thanks for any answers.
I'm a little disappointed that this post is being downvoted because I think it's a very legitimate question. In particular, I appreciate that you asked not what the answer was but instead how you could find it for yourself in the future.
Exploring Local Python Documentation
Python has a very robust built-in documentation system as well as a very active and supportive community. At any point in time, you can use the help function to examine a particular object that you want more information on - this will pull up the documentation for that object. In your example, you could do something like:
help(plt.plot)
to pull up the documentation for the matplotlib.pyplot.plot function. Outside of a running Python process, you can use the pydoc command line tool to read and explore that same documentation. Something like:
$ pydoc matplotlib.pyplot.plot
Running that in the shell will display the same documentation as the help command example.
Writing Documentation
As a good citizen of the Python ecosystem, you'll naturally want to document your own code. This is done pretty simply by adding a docstring to the top of a function, class, or module. Docstrings are denoted with a triple quotation mark """, seen in the examples below:
"""This module contains some example classes and functions"""
class MyClass(object):
"""MyClass does some things"""
pass
def my_function(a):
"""Calculates the sum"""
return(a)
There are many different documentation styles that people prefer, so what you choose is up to you. Though I would recommend the official docstring standards outlined in PEP 257.
Finding Online Resources
It's also often useful to take advantage of online documentation and resources. The official Python documentation includes all of the builtin documentation for the standard libraries as well as a tutorial for developers who are new to Python!
As it seems that you're relatively new to the ecosystem yourself, here's some more resources that you might find useful:
Learn Python the Hard Way
CodeAcademy has a Python track
StackOverflow, obviously
In the end of the SageMath manual they explain why they chose to implement SageMath in Python. One of the items says: "Excellent support for documentation of functions and packages in the source code, including automatic extraction of documentation and automatic testing of all examples. The examples are automatically tested regularly and guaranteed to work as indicated."
This sounds neat, but I haven't found the way to do it. How can I automatically test all the examples that appear in the documentation to my functions?
In principle, you can write your examples using this syntax. Then, you should be able to just do
sage -t path/to/myfile.sage
and apparently that works, given the comment thread!
I want my code to be PEP-8 compliant.
However, reading the PEP8-page everytime I forgot any of the rules is time-consuming. Much faster would be if I had a code example, which demonstrates all PEP-8 rules.
Is there any code example out there which does exactly that?
Here's a gist which claims to be a cheatsheet:
https://gist.github.com/RichardBronosky/454964087739a449da04
You could use Eclipse, the last versions (>2.3.0) of Pydev can include the pep8 checker, so the check will be done in real-time. As soon you wrote the code, the checker will verify it.
I tend to look at code from established projects with contributor policies including PEP. Here are some examples:
sklearn:
Feature selection _from_model.py
logistic.py
Gaussian process _gpr.py
Keras: training.py
Flask: sessions.py
In the examples here, Keras and Flask allow lines longer than 80 characters when necessary which seems common in other projects too. scikit-lean seems to conform exactly in the examples I've seen.
I think this is quite a good example for docstring: Napoleon. Though it's Google's take on docstring rather than official Python.
Get PyDev in Eclipse, the new version include support to make sure that your document is PEP8 compliant and will give warnings on each violation.
Use vim/emacs with plugins. I am vim user so only vim link:
http://www.vim.org/scripts/script.php?script_id=2914
In PHP I was used to PHPdoc syntax:
/** Do something useful
#param first Primary data
#return int
#throws BadException
*/
function($first){ ...
— kinda short useful reference: very handy when all you need is just to recall 'what's that??', especially for 3rd-party libraries. Also, all IDEs can display this in popup hints.
It seems like there's no conventions in Python: just plain text. It describes things well, but it's too long to be a digest.
Ok, let it be. But in my applications I don't want to use piles of plaintext.
Are there any well-known conventions to follow? And how to document class attributes?! PyCharm IDE recipes are especially welcome :)
In Python3 there's a PEP 3107 for functional annotations. That's not useful for 2.x (2.6, specifically)
Also there's a PEP 0287 for reStructuredText: fancy but still not structured.
I use epydoc. It supports comments in reStructured Text, and it generates HTML documentation from those comments (akin to javadoc).
The numpydoc standard is well-defined, based around reStructuredText (which is standard within the python ecosystem), and has Sphinx integration. It should be relatively straight forward to write a plugin for PyCharm which can digest numpydoc.
Sphinx also has references on how to document attributes: http://sphinx.pocoo.org/ext/autodoc.html?highlight=autoattribute