Switching to RestructuredText for documentation

Documentation, Web site and code modifications

Moderators: baguetl, routerov

Locked
User avatar
pouillon
Posts: 651
Joined: Wed Aug 19, 2009 10:08 am
Location: Spain
Contact:

Switching to RestructuredText for documentation

Post by pouillon » Tue Dec 01, 2009 12:35 am

Dear All,

During the lifespan of Abinit 5, we've successfully used Markdown for a certain number of things. Markdown is indeed light, easy to learn, and easy to use. It was perfectly matching the requirements of our former website. However the situation has substantially changed now, and our needs have evolved.

The start of Abinit 6 might thus be a nice opportunity to start using RestructuredText as well. I see 3 good reasons to do so:
    * RestructuredText is almost as easy to learn and use as Markdown, and provides more features;
    * it is used for most Python documentation, as well as in many open-source projects, including Plone (our current CMS);
    * there are advanced tools to automatically build websites out of a bunch of RestructuredText files, like Sphinx.

I will use it for the build system, which will let me include the whole documentation within the source. What I appreciate a lot is its readability.

I'm sure it could be used in other parts of the Abinit documentation too. I'm thinking in particular to the help files, for which it would be useful to easily get HTML and PDF versions at the same time. That would facilitate the maintenance of these files as well. Other possiibilities include the documentation of input variables and that of the test suite, where some files could even be generated by scripts.

That would be great if some people showed some interest in this, as it does not require particular skills in software programming.
Yann Pouillon
Simune Atomistics
Donostia-San Sebastián, Spain

Locked