On 29 mars 10:01, Colin Morris wrote:
> Hi,
Hi,
> I and a few others on Team Tahiti were looking at pylint #2513 ("improve
> documentation", http://www.logilab.org/ticket/2513) and hoping to make some
> progress. One improvement that the whole team agreed would be useful would
> be to have a graphical manual using HTML, based on the text files in the
> /doc directory. Just recently (after getting a start on our own graphical
> manual) we realised that the text files in the /doc directory are in fact
> (if we understand correctly) templates for HTML documents.
>
> We haven't been able to build the documents using the makefile in the /doc
> directory, since we seem to be missing the 'mkdoc' utility (which we haven't
> been able to find). In light of this, we have a few questions:
>
> 1) Where can we download and find information about the syntax of the
> templating engine that's been used for the docs?
search google for ReStructuredText.
> 2) If we were to write an HTML manual separate from the existing
> auto-generated HTML, would that be something that would be useful to the
> community? We find the documentation at
> http://www.logilab.org/project/pylint/documentation somewhat difficult to
> navigate, with its structure seeming a bit haphazard. The HTML manual we
> were envisioning would be based on the same text, but be more easily
> navigable, more logically structured, and perhaps more visually pleasing
> (with some CSS, and images, including screenshots). On the other hand, it
> would not be as easy to synchronize with the text files as their content
> changes, and would probably not be integrable with the logilab site.
That's not an option for us. We definitly want to keep the documentation
in restructured text, html is too much pain to maintain. ReST is however a
powerful language, you can include image, tables, generated toc, etc...
Using bare docutils package (eg the base restructured text implementation),
you should be able to transform the documentation to html to get an idea
of the rendering. Yyou won't get logilab's specific style but that shouldn't
be a problem.
One thing we could consider is using sphinx [1] for a nicer output (and more)
and/or pygments extension for colorized code snippets [2].
Anyway, please to focus on documentation's content.
[1] http://sphinx.pocoo.org
[2]
http://docutils.sourceforge.net/sandbox/code-block-directive/docs/syntax-highlight.html
--
Sylvain Thénault LOGILAB, Paris (France)
Formations Python, Debian, Méth. Agiles: http://www.logilab.fr/formations
Développement logiciel sur mesure: http://www.logilab.fr/services
CubicWeb, the semantic web framework: http://www.cubicweb.org
_______________________________________________
Python-Projects mailing list
Python-Projects@lists.logilab.org
http://lists.logilab.org/mailman/listinfo/python-projects
