[myhdl-list] Documentation status

[Jan D. <ja...@ja...>]

Some words about the status of the MyHDL documentation, in
particular the manual.

In the near future I'll have to write and rewrite considerable
amounts of documentation. Not only about the VHDL stuff: I also
want to rewrite the whole unit testing chapter to show the
use of py.test instead of unittest, and the possibility to
convert test suites.

Recently I became a little worried. For MyHDL, I have reused
the Python documentation flow based on latex, which is a bit
of a mess (based partially on Perl!). I also noticed that a
new system based on Restructured Text (reST) was introduced
in Python development starting with 2.6. The Python docs have
already been converted to the new format, and are further
being developed in it, e.g. for 3.0. The new documentation
generation tool is called "sphinx".

Obviously I don't want to be left with an unsupported flow and
even less to write new documentation in it.
So, even though the new flow is not officially released, I decided
to bite the bullet and try to adapt right away. Not unexpectedly,
the existing Python doc sources have been converted to the new
format using a use-once, throw-away script. I wanted to reuse it,
but as it is now obsolete for Python itself, the conversion
script is already being "phased out". So it was best to act
right away.

After some hacking I managed to convert the current
MyHDL doc sources to the new system, and build html with it.
It works, though I don't like the resulting "look" completely -
but that is just a matter of stylesheets and templates.
I do like the fact that all documentation is in reST format
now - if this works well it might be good idea to move more
parts of the web site to that format.

You can preview the result here:

     http://www.jandecaluwe.com/Tools/MyHDL/dev/html

Jan

-- 
Jan Decaluwe - Resources bvba - http://www.jandecaluwe.com
Kaboutermansstraat 97, B-3000 Leuven, Belgium
     From Python to silicon:
     http://myhdl.jandecaluwe.com