[Simulavr-devel] Rework documentation

[ThomasK]

Hi @list,

I want to rebuild documentation. First step is done: building web site 
and documentation with sphinx. Next step: reorder documentation and make 
plans, what to change and to add. The goal is to substitute texinfo 
documentation after all. (and to have single source for web site AND 
documentation)

Web site will have the following content:

- introduction (with a code example and how to use simulavr standalone 
and with gdb)
- features (from texinfo documentation)
- usage (from texinfo documentation)
- download (new chapter, at the moment it shows old download packages only)
- build (from texinfo documentation)
- todo (new, it's at least a copy of TODO file in source root)

Documentation will have the following content:

- copyright (as from texinfo documentation, this is the document 
copyright, not the program license)
- introduction (same as web site)
- features (same as web site)
- download (same as web site)
- usage (same as web site)
- tclgui (from texinfo documentation)
- build (same as web site)
- verilog (from texinfo documentation)
- examples (from texinfo documentation)
- platform (from texinfo documentation, maybe it's obsolete, in the 
moment here are some comments for gentoo platform, but old. If this is 
needed, I'd propose to move it to build chapter, there is also a 
subchapter for Windows/MinGW)
- limitations (from texinfo documentation)
- helpwanted (from texinfo documentation but stripped, so it's very 
short in the moment)
- license (new chapter, but in my opinion it's needed, in the moment 
it's empty)

An example for documentation pdf (MY current state) is to find here:
http://download.savannah.gnu.org/releases-noredirect/simulavr/manual.pdf

One necessary question: it's necessary to get documentation also in html 
or it's enough to get it as pdf?

Next question: whats necessary to add? There are 3 positions now on my 
(!) list:

- checklist and howto add a new controller (from Onno)
- checklist and howto make a release (from Jörg)
- howto make web site and upload to savannah

And a connected question: it is useful, to add it straight to one long 
documentation with all (where are parts, which are useless for users) or 
it's a better idea to split documentation in 2 parts?

This is my proposal:

- user guide: description, usage, how to get it, usage verilog, python 
and tcl interface, mailing list, reporting bugs etc., license
- developers guide: how to build, configure options in detail, 
checklists and other development howto's, where to get source, mailing 
list, reporting bugs etc., license

cu, Thomas