Add documentation

[macfreek]

Most files in the doc folder are rather empty. I haven't find a big need for it, but perhaps we should either remove the empty files or fill them :)

[twoolie]

certainly more tests are better. Please be my guest.

[stumpylog]

Ignoring the spelling mistakes in the commit message, I did some basic filling out of the documentation. It could use more, but it's a start.

[twoolie]

@stumpylog Thats fantastic work. I'm pulling it in now.

[macfreek]

@twoolie I don't see the pull request, nor the pull.
@stumpylog Thanks a lot! If you have not done so, could you make a pull request?

[macfreek]

I just had a look at Sphinx. I assumed it could create reStructuredText (rst) from the docstrings, but it seems mostly aimed to create HTML from reStructuredText with optionally docstrings mixed in.

Manually maintaining class and method documentation in two places (in the doc folder and in the Python source) does not seem very useful to me.

Two questions:

1. What should be the authoritative source of documentation? I would suggest the source, perhaps with some tutorial-like text elsewhere.
2. Where do we like the documentation to appear? I presume in the downloads and on the GitHub site.

a. Should the downloadable documentation be text or HTML
b. Should the documentation on the GitHub be in the code or on the wiki

I presume we like to use reStructuredText for formatting, as that it the Python standard, and is supported by GitHub in both the code and on the wiki.

[macfreek]

FYI, since I wasn't able to figure out how to use Sphinx to generate rst files from Python docstrings, I asked the question on the mailing list: https://groups.google.com/d/topic/sphinx-dev/3BdP0ywfnaI/discussion

[macfreek]

@stumpylog Hi, did you fill the rst files by hand, or did you use a tool to do it automatically? If the later, may I ask how?

[stumpylog]

I filled them in by hand, mostly based of comments and docstrings already in the code. A tool that can take the docstrings and output rst or other documentation would be more consistent that I was.

[macfreek]

Last night I got frustrated with Sphinx. The documentation and tool seem to assume that I know what it's doing. I can run it, but it apparently it was using some cached result in some binary .doctree format. I have no clue which tool is making which mapping (I presume it's going from rst to doctree, from docstring to doctree, from doctree to html, from doctree to text), but lacking useful feedback from the tool I'm not sure and working in the dark.

doc/conf.py (a Sphinx config file) was added in d86217e. While this commit was tagged as a merge, it seem that neither parent contained the file. @twoolie did you create this file? Do you have any clue how Spinx works? With some luck, it's just me who is completly bonkers, and you or some other sane person can explain it to me.

[stumpylog]

I had a look around at a few documentation tools. Epydoc is dead simple, but it has it's own flavor of markup, and quite frankly isn't very pretty. It creates documentation that is very similar to Javadocs. For Sphinx, have a look at sphinx-apidoc. I was playing around with that, and it seems to work well, and was a lot simpler than the quickstart. Using the -F option, it can create a conf.py, and makefile for building html documentation.

[macfreek]

@stumpylog I looked at your sphinx config, and got mine to finally work. Turns out my error was to run

sphinx-build -b text .. build/text

instead of:

sphinx-build -b text . build/text

(I somehow assumed I need to point to the folder where nbt was located, but it turns out it is just using sys.path). This lead to some weird errors because it was searching for .rst files in all subfolders, and also found the old ones which I have mv-ed aside. This caused sphinx to crash because it couldn't find some files.)

Anyway, I got it working and committed some preliminary files, based on your work

• The original conf.py was retained, which was created by twoolie last year, which included his name an all.
• A Makefile was aded, but I made some changes in how it is called
• conf.py sets sys.path to make sure the nbt in this folder is used, and not some other nbt installed in a site-packages elsewhere on a computer.
• Your 29a6f17 was included as well. You seem to use 8-space indentation. I changed that to tab for consistency with the rest of the code. (PEP 0008 specifies 4-spaces as standard, but tWoolie prefers tabs. I'm fine, as long as it's consistent).
• The examples and original NBT specification are added too, but they are not formatted yet.

If you want to format the docstrings, please do! I recommend that you follow the guidlines of PEP 287 and PEP 257.

If you make pull requests, it is appreciated if you could use tabs (see #27, and yes I know this is different from what our BDFL has dictated in PEP 0008).

If you have time, I haven't been able to figure out these:

• The methods and classes are included in alphabetic order. I would prefer file order, but don't know if that's possible.
• I can't seem to show the nbt._get_version() in nbt.__init__, despite a :private-members: directive in index.rst.
• The specification.rst needs formatting.

PS @stumpylog if you want to make a merge, you may consider merging (git pull twoolie bda036bf18228a8f2f8cb5c1d61cea766aa12558 instead of git pull twoolie master provided you have a git remote twoolie) to avoid all sorts of conflicts.

[macfreek]

Are there suggestions what to include in the git repository and/or setuptools distribution? The .rst to html works fine, but .rst alone is not helpful. Should we include the html, or simply say in the README that users can generate documentation with

cd doc
make html
make test

If there are no suggestions, I'm going to close this issue.

[macfreek]

Closing this, now that #60 provides automatic doc creation for the wiki

Checkout the NBT.wiki repository in the same directory as the NBT checkout, and run:

cd doc
make wiki