setup documentation toolchain

[Byron]

The bcore code base is more than a year old by now, was upgraded and patched up, leaving the existing rst documentation in a miserable state. What's there might be outdated, miss the main points, or may simply not be a good read. Other pieces have no documentation at all.

This ticket is not about writing the actual documentation, but to determine the tools used to produce documentation, may it be in-code docstrings, or custom written high-level manuals.

Whatever result I come up with, it must be easily transferable to all the other repositories I have, and integrate nicely with any existing build system, like bbuild .

Wishlist

The fat ones are those that I don't want to live without.

• show up on read the docs
• easily build static documentation
• includes a tool to produce browsable documentation from source
• has a tool to build high-level documentation in an easy to use, yet powerful enough markup language
• toolchain supports multiple outputs natively, namely PDF, ePub (may also be provided by readthedocs)
• Setup a workflow that encourages sketching the documentation while the documented item takes shape.
• Help making code easily usable by providing sublime text snippets right away !! This will be the killer feature make using frameworks easy. After all, you don't want to study docs or copy-paste boilerplate.
• unit-testable examples. Without this feature, docs go out of sync way too easily
• hierarchical documentation allows to build compendiums, which are made up of documentation of various projects.
• multi-version docs - various versions of the documentation must remain accessible, each release has its own. gh-pages can't do it natively, readthedocs should be able to.

Experiment

Try out the toolchain using the existing documentation of bcore, without editing it much except for the possibly required format conversion. Be sure it works from start to end. #19 seems like an ideal candidate for this.

[Byron]

I would clearly prefer markdown over rst, as it is easier and quite en-vogue, which nice tools alongside of it. It seems that mkdocs can't include documents.

This is in fact the key-feature of doxygen, using it's snippet tag to allow inclusion of regions of files. It seems that sphinx can't do it either.

All I want is verbatim, syntax highlighted inclusion of other files based on marked regions.

doxygen so far is the only system I know that can do it, but it's not the greatest to write full documentation in, as it simply doesn't look that good.

Ideally, I am linking from doxygen (i.e. in-code comments) to the respective markdown on readthedocs.

As mkdocs seems so great, I would consider starting with it anyway, and contribute what I need.

[Byron]

@mottosso you are welcome to let me know about your experience, maybe I am missing something obvious ?

[Byron]

First draft of docs now online on github pages.

Something that will have to be thought of when doxygen enters the field will certainly be how both can be combined on one site. Something would have to generate a custom index, or easier, doxygen output might just live within the mkdocs output, which should allow cross-linking.

[mottosso]

Yeah, I like mkdocs. I would suggest keeping user and automatic docs separate - mkdocs has been good for user docs so far, haven't found any comfortable automatic kind just yet, especially not doxygen as it makes you dilute your code with junk.

[mottosso]

About the draft; I still think it's wordy, without providing much information. I'm missing a center-piece, the one-liner that sums up what it does. It's like a function, if you can't explain it shortly, it's too long. Maybe the "bcore" package is too big to be explained simply?

Have a look here, especially at "the winning difference" http://my.copyblogger.com/basic/10-rock-solid-elements/

[mottosso]

Reading the bcore README, one more thing comes to mind. http://en.wikipedia.org/wiki/Show,_don't_tell

For example, as an alternative to this:

The requirements are kept minimal, which is why you need nothing more than:
* a python 2.6 or 2.7 interpreter running on Linux, OSX, Solaris or Windows

You could write

Requirements
* Python 2.6-2.7

And let the reader determine whether or not this is minimal.

And as an alternative to

* a simple framework for writing and running quality checks

You could write

* A framework for writing and running quality checks

And demo how it works, letting the reader come to the conclusion about whether or not it is simple.

[Byron]

Thanks for the feedback.

Doxygen is for api docs, and i believe those are needed. To my mind proper desciptions of an api is a requirement, despite of the doc generator or markup used. As elaborate comments can be distractive, it would be great to be able to fold comments. Will have a look in sublime.

When I start reviewing the existing docs, i will remind myself of your advice. So far, the docs were just migrated from rst.

The docs for the 'be' tool should be the first to review, as they are written from scratch.

[mottosso]

Hey,

I'm going through your docs at http://byron.github.io/bcore/bcmd/

Good job! Just one thing that keeps popping up that I think could be made better, which is that the word "easy" is far too common. I would safely assume that any solution is intended to make the problem at hand easier - saying something is easy doesn't necessarily make it so.

Again, show, don't tell. Let the reader figure out whether your solution is easy. And if you can't show, I would avoid telling altogether and save it for when you can show.

Other than that, looks like it's shaping up nicely!

[mottosso]

I would also tone down a bit on the word arbitrary. This is something you could let the reader witness as well, instead of being told.

Possibly via an example, possibly via exposition :)

[Byron]

Thanks for the kudos ! You should see it once I actually started on working on them, assuming I can incorporate your suggestions :). But it shows one thing: it benefits from the mkdocs presentation already.

[mottosso]

Reference of things that could be expressed via examples or exposition, in case you change it:

With bcmd it is already easy to create complex, plugin-based..

..commands whose parsers can form arbitrary trees

This is how you define a simple command..

SubCommands allow you to create complex commands yet modularize that functionality nicely

it is very easy to extend your command at runtime

And that's just from one page. :) http://byron.github.io/bcore/bcmd/

This might help guide your approach as well: http://www.ted.com/talks/simon_sinek_how_great_leaders_inspire_action