Develop Reference

TexSoup for Bib-Files

this is my first question so I will try to do everything as proper as possible.
I am currently using LaTeX to write my documents at my University because I want to use the powerful citing capabilities provided by BibTeX. For ease of use, I am writing on scripts that will implement my .bib-files into my .tex files easier and allow easier management of my .bib-files. As I am using Arch Linux, I did this in bash, but it is a little clunky. Therefore I wanted to switch to python, as I came across the TexSoup-library for Python.
My issue is now, that I cannot find resources regarding the use of TexSoup for .bib files, I can only find resources on .tex-files. Does anybody know, if and if yes how I can use TeXSoup to find books / articles or other entries in my bib-files with python (or the TexSoup-library)?
with open("bib_complete.bib") as f:
soup = TexSoup(f)
print(soup)
This is a code sample I am trying to use, but I don't know how to look for entry names or entry-types with the package. I would really appreciate if someone could guide me to good resources if they exist.
I hope my writing was comprehensive enough and not too long.
Thanks everybody!

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 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.

Search function with PyGTKsourceview

I'm writing a small html editor in python mostly for personal use and have integrated a gtksourceview2 object into my Python code. All the mayor functions seem to work more or less, but I'm having trouble getting a search function to work. Obvioiusly the GUI work is already done, but I can't figure out how to somehow buildin methods of the GTKsourceview.Buffer object (http://www.gnome.org/~gianmt/pygtksourceview2/class-gtksourcebuffer2.html) to actually search through the text in it.
Does anybody have a suggestion? I find the documentation not very verbose and can't really find a working example on the web.
Thanks in advance.

The reference for the C API can probably be helpful, including this chapter that I found "Searching in a GtkSourceBuffer".
As is the reference for the superclass gtk.TextBuffer

Here is the python doc, I couldn't find any up-to-date documentation so I stuffed it in my dropbox. Here is the link. What you want to look at is at is the gtk.iter_forward_search and gtk.iter_backward_search functions.

Producing documentation for Python classes [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 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.