Producing documentation for Python classes [closed] - python

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm about to start a project where I will be the only one doing actual code and two less experienced programmers (scary to think of myself as experienced!) will be watching and making suggestions on the program in general.
Is there a good (free) system that I can use to provide documentation for classes and functions based on the code I've written? It'd likely help them a lot in getting to grips with the structure of the data.


I have used epydoc to generate documentation for Python modules from embedded docstrings. It's pretty easy to use and generates nice looking output in multiple formats.


python.org is now using sphinx for it's documentation.
I personally like the output of sphinx over epydoc. I also feel the restructured text is easier to read in the docstrings than the epydoc markup.


Sphinx can be useful for generating very verbose and informative docs that go above and beyond what simple API docs give you. However in many cases you'll be better served to use a wiki for these kind of documents. Also consider writing functional tests which demonstrate the usage of your code instead of documenting in words how to use your code.
Epydoc is very good at scanning your docstrings and looking at your code to generate API documents but is not necessarily good at giving much more in-depth information.
There is virtue to having both types of documentation for a project. However if you get in a time crunch it is always more beneficial to have good test coverage and meaningful tests than documentation.


I use Sphinx for my project, not only because it looks good, but also because Sphinx encourages writing documentation for humans to read, not just computers.
I find the JavaDoc-style documentation produced by tools like epydoc quite sad to read. It happens all too often that the programmer is mindlessly "documenting" arguments and return types simply because there would otherwise be a gap in the API docs. So you end up with code line this (which is supposed to look like Java, but it's been a while since I wrote Java, so it might not compile...)
/**
* Set the name.
*
* #param firstName the first name.
* #param lastName the last name.
*/
public void setName(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}
There is a very small amount of information in this so-called "documentation". I much prefer the Sphinx way where you (using the autodoc plugin) simply write
.. autofunction:: set_name
and Sphinx will then add a line to your documentation that says
set_name(first_name, last_name)
and from that every Python programmer should know what is going on.


See answers to can-i-document-python-code-with-doxygen-and-does-it-make-sense, especially those mentioning Epydoc and pydoctor.

Related

is there a detailed documentation for libpd Python API?

I'm working with libpd for Python, and I can't seem to find a detailed API. I would at least like a simple list of methods available.
The best I can find is here: https://github.com/libpd/libpd/wiki/Python-API
Which has a heading for "Detailed API Documentation", but under that, it just says: "Anyone care to elaborate or link here?"
If it does not exist, I would like to document it as I go, but if it already exists somewhere, that (and so much figuring out) would be a bit of a waste of time.
Thank you!!

assuming that you are really asking for a detailed documentation for the API rather than a detailed API:
the python-API of libpd is just a thin wrapper around the C-API.
Since the C-API is documented in the wiki you better just use that one.

So, what I found was you can use the C API documentation, BUT there are more methods and a PdManager class added to the Python version which were not documented (which were the things I wanted to know about)
So I documented those extra things here:
http://mikesperone.com/files/libpdPythonAPIdoc.pdf
it's not super detailed and many things are just references to the methods in the C API, but hopefully it will help others who are also looking

Python and JavaScript/AngularJS documentation on the one server?

The advantages of this approach include:
Consistent docstring syntax everywhere
Centralsied documentation server; find all your docs in one place
Search and jump-to-source from any documented function or class; in either language
Are there any modules integrating with Sphinx or similar; which generate+put your JavaScript and Python documentation in one place?

I am not sure if your question is about public documentation or in-house documentation of some of your projects.
For the former you want to see this: http://devdocs.io/
Also devdocs document scrapers are open source, so you should be able to use them for your own projects to build custom devdocs.io.

Mako Templating

I am new to Python and Mako and such. My question might seem dumb, I apologise in advance but I looked at the docs and could not find it.
In .py files, I can use # character to take notes. I can also use
'''
notes
notes
'''
My questions:
How can I do this with .mako files?
What is the common name for this? (taking notes, annotating..)

http://docs.makotemplates.org/en/latest/syntax.html#comments
In almost all programming languges and related technical formats, this feature is called a comment.

Python pefile member question

Gang,
I apologize if this is a really dumb question... I am wanting to use the super convenient python script pefile (http://code.google.com/p/pefile/) that parses an executable and lists particular information about the PE structure. My question is where can I find information about how to access particular members of the executable? I've scoured the wiki and read the usage examples but that documentation only covered 4-5 members. What I am wondering is if you guys have a list of members I can access to display the information I care about. So specifically, if I wanted to list the Stack Commit Size of an executable, does it look like this: pe.FILE_HEADER.StackCommitSize, obviously I can run this code and figure it out but have you guys seen API DOC floating around that I find the members i need?
THANKS!

From the PE docstring:
Basic headers information will be available in the attributes:
DOS_HEADER
NT_HEADERS
FILE_HEADER
OPTIONAL_HEADER
All of them will contain among their attributes the members of the
corresponding structures as defined in WINNT.H
So, look at winnt.h and you'll see which attributes are available.
Or just read the source code for the module. It's big, but everything you need to know is in there.

You can generally find everything that is in a PE file in the Microsoft PE/COFF specification.
Once you've looked there, you know that the StackCommitSize is in the optional image header. Then all you have to do is to look for the corresponding structure in pefile, which usually bears a similar name, if not indeed the very same name. In this case:
pe = pefile.PE("C:\\Windows\\Notepad.exe")
print pe.OPTIONAL_HEADER.SizeOfStackCommit
Will give you what you want.
If you have trouble finding SizeOfStackCommit (after you've found it in the specification), just use your quick find on the source code. It's as easy to read as you can get, and I don't think you'll have any trouble finding the required structure.
Now, there probably aren't any API docs for pefile itself, but as you can see there's really no need for it, since it's just a nice Pythonic wrapper around the PE specification itself.

Python based web reporting tool? [closed]

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 6 months ago.
Improve this question
I have a question for those of you doing web work with python. Is
anyone familiar with a python based reporting tool? I am about to
start on a pretty big web app and will need the ability to do some end
user reporting (invoices, revenue reports, etc). It can be an existing
django app or anything python based so I can hook into it.

ReportLab
Welcome to the ReportLab Open Source site. ReportLab is a library for programatically creating PDF documents. It's a fast, flexible, cross platform solution written in Python.

Or go a little higher level than reportlab: xhtml2pdf - now WeasyPrint (built on top of reportlab)
From the website:
Translates HTML and CSS input into PDF files
Is written pure Python and therefore platform independent
Supports document specifics like columns, headers, footers, page numbers, custom Postscript and TrueType fonts, etc.
Best support for frameworks like Django, Turbogears, CherryPy, Pylons, WSGI
Simple integration into Python programms
Also available as stand alone command line tool for Windows, MacOS X and Linux

Most reporting tools are stuck in the '80s: a time when you 'painted' a report intended to be printed that completely lacked integration with other reports.
Sometimes we still need that. If you need to print an invoice, you're pretty much stuck with that kind of functionality. But in general, most reporting these days consists of multiple queries/charts/graphs/tables per page with drill-down built directly into it.
If you've got enough of a need go with an OLAP tool - then you don't even code the reports, your users (theoretically) can. If not, I've seldom seen a scenario in which a "reporting tool" was better than using something like Chart Director with a language like php, perl, python, ruby, etc.

Try to have look at the Cubes - Light-weight OLAP framework for Python. It is just partial solution for your problem, but I think it might help.
Sources at github
Documentation
Blog with tutorials
You can either use Python to do OLAP/aggregated browsing or you can run an OLAP HTTP Server (called Slicer). Here is an example using HTTP Server: Open Public Procurements reporting. The front-end is PHP which accesses Slicer server through HTTP. Example of server can be found here with documentation for the server can be found here.
Currently the framework provides SQL backend using SQLAlchemy, so you can use any DB that can SQLAlchemy has engine for.
Reports in form of charts, tables & stuff, including JS front-end framework are planned. Just wanted to help at least with lower OLAP layer.
Let me know if you have any questions, I am the author.

Also have a look at myDBR a tool that allows you to define your reports in the database (using stored procedures) and then takes care of the layout and formatting of the data.
Even though myDBR is a PHP application, it does not require any PHP coding, just install the application and embed it as iframe in your own app.

I've been working on a recent addition to this. It allows you to create HTML reports from Python which you can share as standalone HTML files. This means you can have interactive components - such as table viewers and interactive plots (which have become a lot more popular since this question was originally posed).
Currently it supports pandas DataFrames, Bokeh, Plotly, Altair, JSON, and Markdown components.
For instance:
import altair as alt
import pandas as pd
import datapane as dp
df = pd.read_csv('https://query1.finance.yahoo.com/v7/finance/download/GOOG?period1=1553600505&period2=1585222905&interval=1d&events=history')
chart = alt.Chart(df).encode(x='Date', y='High', y2='Low').mark_area(opacity=0.5).interactive()
dp.Report(dp.Table(df['High']), dp.Plot(chart)).save(path='stock_analysis.html')
It's still early, but check it out: https://docs.datapane.com

I was doing some research and found about awe. It runs a small webserver which can do realtime updates on a page and allows for more complicated report layouts.
It has documentation and examples and can give you something up and running, quickly.

Categories

Resources