Documentation

[bennuttall]

I feel we should provide documentation for the API when it's complete, and it might be good to make a start on it once we know what it will look like.

My preference would be to write them in markdown, located in /docs/. For now just browsable markdown on GitHub would suffice (like raspberrypi/documentation) but later we could move to a hosted project using mkdocs or similar.

Thoughts?

[doismellburning]

My preference would be generating the documentation from docstrings, thus keeping it as close to the code as possible and reducing the risk of bit rot.

[pozorvlak]

Docstrings are great for detailed API documentation, but less good for
overview and tutorial documentation. I think there's a need for both.
Preferably with lots of examples.

On Sun, Sep 28, 2014 at 12:13 AM, Kristian Glass [email protected]
wrote:

My preference would be generating the documentation from docstrings, thus
keeping it as close to the code as possible and reducing the risk of bit
rot.

—
Reply to this email directly or view it on GitHub
py3minepi/py3minepi#8 (comment).

[jonathanfine]

I'd like us to provide documentation that children and teachers can use. And I'd like it to be part of the default Raspbian install. Does anyone know what will work well on a Raspberry Pi?

It would also be nice if children could on the raspi write their own documents. But at this time I don't see it as a must-have.

[dbrgn]

Usually I'd go for Sphinx, but in this case I think something like mkdocs would be better. The docs should be aimed at children & teachers, not at developers.

Another issue would be localization. It would be great if the documentation could be translated into different languages. Most children in non English speaking countries don't speak English yet. Does someone know if mkdocs supports that?

I also took a look at https://www.gitbook.io/, which was used for http://djangogirls.org/. It looks great, but I'm not sure whether you could generate the HTML locally too, without using their service.

[ghickman]

Let's keep this simple to start with and build up as we go. Docs have a habit of being a black hole if you overreach too early.

In roughly this order:

• API documentation generated from the docstrings (hosted on mkdocs/readthedocs) intended for developers [of this library] and end users as a lower level reference.
• Prose documentation intended for library users, ie teachers and kids.
• Tutorial documentation

Any of these sections could, however, be started as a way to document the ideal API.

@jonathanfine – I believe the current implementation of this library is in the Raspbian repos already so hopefully we can replace that with this one. @bennuttall or @asb – would we need to build another format for packaging the library?

@jonathanfine – I'm not sure if I follow what you mean about children writing their own docs but that seems out of scope for this project?

[bennuttall]

I maintain documentation for Raspberry Pi - we have documentation and learning resources - both sets are written in markdown and parsed in to HTML templates, currently using PHP. However I'm currently revamping the resources for some new templates, and will use Python to pre-render to HTML which will be (a) deployed to the website and (b) packaged in Raspbian.

It would be nice to do something similar for Minecraft docs - provide a related package containing the docs which could be opened in a simple browser on the Pi, like the Debian reference.

mkdocs is a great project but is not very mature at present.

[bennuttall]

To be honest, the documentation/examples/samples could just live in our usage guide page.

[dbrgn]

I really like that usage guide. Would be great if that were translateable. (I live in Switzerland.)

[bennuttall]

Translations are a plan, but we don't have a solution yet :(