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!
Related
I'm writing some Python code that's being checked with pylint with the docparams extension. This requires documenting function parameters in their docstrings. I have a tendency to try to decompose functions as much as possible and end up with lots of functions that call other functions - often sharing many of the same parameters. This can lead to lots of redundant (copy-pasted) documentation in the docstrings. Is there a recommended way of dealing with this type of situation?
I'm going to run into this same problem later while working on a Pyramid app, so I googled and found docrep. I think it'll satisfy both of our needs.
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
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
We are currently looking for ways to help the non-programming members of the sysadmin group familiarize themselves with Python scripts used for day-to-day sysadmin tasks.
Does anyone have any suggested documentation tools or best practices that we might find useful for this purpose?
Edit to address S.Lott's comment:
First, my apologies for being too brief on my initial question. My primary goal is to make sure that someone, even a non-programmer, is easily able to troubleshoot my scripts if I'm not in that day or if I leave the organization.
What I'm looking for is practices used by other people who have the "script coder" role in a technical group such as a sysadmin team. For example, before I begin the process of scripting a task, I've gotten into the habit of first writing an article in our shared wiki explaining each step in detail. I then base my Python scripts on the article--using it as pseudo code.
Other examples of the sorts of things I'm looking for:
Using tools such as Sphinx to provide easily available doc
Having group discussions to go over code before putting in production
Allowing group members to first go over the process manually (we usually go this route but perhaps we should make it a more common practice)
Or, just as valuable if not more so, negatives such as:
Found that heavy commenting is a waste of time because the logic flow is still foreign to non-programmers
Lean toward using pexpect because of the verbosity lost when using high level modules
The above are just examples of things I thought of. Hope this clarifies the question! As always, thanks SO'ers.
There is a book on this subject - "Python for Unix and Linux System Administration".
http://oreilly.com/catalog/9780596515829
And an article on developer works which might provide you the flavor that you may want to follow.
http://www.ibm.com/developerworks/aix/library/au-python/
And almost any one, irrespective of how, he is going to apply it, would want to work on the basics of the language itself. There is a good starter on web apart from tutorial that is distributed along with standard python distribution.
http://diveintopython3.ep.io/
I find that using argparse as the basis for script invocation parsing/routing tends to produce a decent first line of documentation. If used as intended, your sysadmins can run some_script --help to get a description of the script's purpose and a summary of its options.
It can be fairly trivial to link the documentation sources used by the parser building code to the actual docstrings of functions and classes in your code and that of the script itself. It depends on the complexity of the script, but this can often be a low-effort way to get sufficient documentation.
I'm currently working on a simple wxPython app that's essentially document based. So far I've been manually implementing the usual open/save/undo/redo etc etc stuff.
It occurred to me that wxPython must have something to help me out and after a bit of searching revealed the docview package.
At this point though I'm just not quite sure how to hook everything up and get things started. Anyone got any good links or hints about places to start?
The docs seems to be a little thin about this and Robin Dunn's wxPython book doesn't really cover this package at all.
You might take a look at the docviewdemo.py from the wxPython Docs and Demos:
on my machine they are located:
C:\Program Files\wxPython2.8 Docs and Demos\samples\pydocview\
C:\Program Files\wxPython2.8 Docs and Demos\samples\docview\
In addition to the ones mentioned, there is quite an extensive example docview/pydocview in the samples\ide. If you want it to run you will have to make a few code corrections (I have submitted a ticket that outlines the fixes at trac.wxwidgets.org #11237). It is pretty complex but I found it handy to figure out how to do some more complex things. For example, samples\ide\activegrid\tools\ProjectEditor.py is built from scratch and has undo support etc rather than just relying on a control that does everything for you already. That way you can see how things are supposed to be done at the detailed level. The documentation is rather useless in that regard.
If you have decided against using docview/pydocview I have a spreadsheet application built on wxPython that you may find useful as an example. While it does not implement a document view framework it does have some characteristics of it and I've implemented an undo/redo system. Check it out at http://www.missioncognition.net/pysheet/ I'm currently working on a pydocview based app so I expect that to be up on my site eventually.