Documentation Production System
===============================
Mentoring Org: TurboGears
Student: Bruno Melo
Mentor: Armin Ronacher
Dear Community,
First of all I would like to thanks the TurboGears community for help me
during this GSoC, specially my mentor Armin Ronacher, Mark Ramm, Sanjiv,
and Christopher Arndt for the various useful conversations.
My project was create (or improve) the new TurboGears documentation
infrastructure. These are the features implemented (until now):
# Include external resources
- From local files
- From sections of local files
- From a VCS (revision or tag), Subversion and Mercurial supported
Some examples (from Wiki20):
(...)
<div style="float:right; width: 10em;"> Viewing
<!-- ##{pagename section} -->
<span py:replace="wikipage.pagename">Page Name Goes Here</span>
<!-- ## -->
<br/>
You can return to the <a href="/">FrontPage</a>.
</div>
(...)
and in the documentation you write:
.. code:: Wiki-20/wiki20/templates/page.html
:section: pagename section
you can too get a specific revision of this code:
:revision: 4831
or a tag (except in SVN, where tag is simply a directory and put direct in
path):
:tag: ver2.1
# Test sample projects
For a sample code in the docs you can associate a unit test to make sure
that
the sample is functional.
Any test failure will generate a documentation warning.
Example:
In the WikiWords section of Wiki20 tutorial you could write:
.. test:: Wiki-20/tests/test_wikiwords.py
and all options from Nose is available.
# Compress sample projects
Compress the sample from a tutorial to the user download.
Example:
Put this (in the beginning of page):
.. archive:: Wiki-20/
:file: Wiki20.zip
and a link to the zip file is created in this way:
Download the sample project :arch:`here`.
What's missing??
# Comment System
The first was approach let the Sphinx build a Web project with this
capability,
but I'm developing this system in another way, I'm creating a TG2/Pylons
project
to persist all comments communicating by JSON with the Sphinx documentation.
# Documents
I need to write more examples, the Wiki20 tutorial is using some of these
features,
but some of them need to be fixed.
Write some docs about how to use these extensions to help contributors in
their
task.
Some clarifications
~~~~~~~~~~~~~~
Since the beginning of this month I begun work in a second company (and I
think
that mostly due my involvement with this GSoC project) and the more complex
part
of project is until this week (I'm working more than ten hours a day during
this
phase). When I stay in home is only to sleep :( ... BUT this situation have
time to finish
and so I can complete the missing part and keeping working to improve the
docs.
Thanks all of you very much!!
Best Regards,
--
bj
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"TurboGears Trunk" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/turbogears-trunk?hl=en
-~----------~----~----~----~------~----~------~--~---
