Add documentation about nbt HOT 13 CLOSED

certainly more tests are better. Please be my guest.

from nbt.

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.

from nbt.

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

from nbt.

@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?

from nbt.

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.

from nbt.

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

from nbt.

@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?

from nbt.

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.

from nbt.

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.

from nbt.

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.

from nbt.

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

from nbt.

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.

from nbt.

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

from nbt.