Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Write module documentation #29

Closed
giampaolo opened this issue May 28, 2014 · 6 comments
Closed

Write module documentation #29

giampaolo opened this issue May 28, 2014 · 6 comments
Labels
Component-Docs enhancement imported imported from old googlecode site and very likely outdated

Comments

@giampaolo
Copy link
Owner

From billiej...@gmail.com on July 23, 2007 22:11:46

We actually lack documentation for the module.
I was thinking of writing it by using Wiki service provided with Google Code.
Alternatively it would be also good using LATEX format complying ourself
with the standard Python doc.

Original issue: http://code.google.com/p/pyftpdlib/issues/detail?id=29

@giampaolo
Copy link
Owner Author

From jlo...@gmail.com on July 28, 2007 04:00:12

I think first and foremost we should fully document the module using detailed
docstrings. There are a number of tools for creating documentation from docstrings
that let you use formatting similar to javadoc, which might be worth looking into
also. I found epydoc, which also has a decent summary of several tools 
available for
Python documentation: http://epydoc.sourceforge.net/relatedprojects.html With 
regards to the writing wiki or LaTeX documentation, the wiki will be convenient
and easy for us to use. However, if we want to provide documentation with the
pytftpdlib package (e.g. HTML doc pages), then the wiki will not be able to be used
for that purpose. I recommend that we use the wiki for writing up interesting pieces
of information that don't necessarily make sense to include in 'formal' 
documentation
for a module. For instance, we could use it to include interesting uses of pyftpdlib,
samples of code, FAQs, etc. 

For documentation included with pyftpdlib, we can use a tool like epydoc or one of
the projects listed above to generate HTML/PDF API and usage documentation to put in
the doc/ folder. IMHO, learning LaTeX just to write docs for a module seems overkill
and it would be easier for us to use a convenience tool to generate the docs from the
module itself. This also has the added benefit that users can use pydoc to retrieve
basic doc information,

@giampaolo
Copy link
Owner Author

From billiej...@gmail.com on August 06, 2007 02:52:29

Labels: Milestone-0.2.0

@giampaolo
Copy link
Owner Author

From billiej...@gmail.com on August 16, 2007 22:28:23

Docstrings have been updated by Jay Loden into SVN revision #70 for module to include
consolidated version of the module overview as well as cleaning up some of the
wording and comments enhancements.

Actually some provisional FAQs, API Reference and Tutorial wikis are available on a
temporary GoogleCode project I created for writing drafts and doing tests: 
https://code.google.com/p/billiejoex/w/list Note that all wikis refers to the 
upcoming 0.2.0 version which breaks some backward
API compatibilities with the current one.

Using Wiki seems to be a good choice excepting for the API Reference which should be
written by using one of the tools you mentioned.

I find reasonable to provide also wiki papers with the package release. A kind of
python script converting Wiki markup language into an HTML page could be optionally
written.

@giampaolo
Copy link
Owner Author

From billiej...@gmail.com on September 13, 2007 08:51:57

Added FAQ and Tutorial wikis (svn revision #100 ).
I'm waiting for Jay Loden to take a last look at them, then I'll make a dump for
converting them into static HTML files to include into distribution.

Status: Finished

@giampaolo
Copy link
Owner Author

From billiej...@gmail.com on September 17, 2007 09:44:50

Wikis dumped into HTML static files added into 0.2.0 release which is now 
finally out.

Status: Fixed

@giampaolo
Copy link
Owner Author

From billiej...@gmail.com on May 02, 2008 11:27:42

Labels: Version-0.1.1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Component-Docs enhancement imported imported from old googlecode site and very likely outdated
Projects
None yet
Development

No branches or pull requests

1 participant