Hi everyone,

because I mainly did the setup for the current reference guide I would like
to say some words about the current structure and how the wiki on
livedocs.dojotoolkit.org is transferred to the statically generated
reference-guide.

Just for better understanding, i would like to point out the two
documentation systems we currently have. Both systems are using an extended
restructured text markup (e.g. .. code-example, ...):

Wiki
------
On livedocs.dtk.otg we are using a moinmoin wiki, that has a simple
folder/file structure for saving the documents and doing the versioning.

Sphinx (static generation)
-----------------------------------
The other system is the respository at
http://svn.dojotoolkit.org/dojo_doc_wiki/ where we are using the
documentation system Sphinx (http://sphinx.pocoo.org/: written in Python and
it is also used for writing the Python documentation) for generating the
static documentation you currently see at
http://dojotoolkit.org/reference-guide.


For creating the static documentation I currently copy the "pages" directory
of the wiki and use the script
http://svn.dojotoolkit.org/dojo_doc_wiki/_addon/moinconverter.py to generate
all files that can be consumed by the reference guide. Until this stage
everything could be automated, but afterwards starts a manual task to
cleanup the generated documents.

That is because:
- Both systems use a different method for linking
- Sphinx has a concept for generating a Table-Of-Content

Since release 1.3 I do this process for every new Dojo release and I did the
last conversion at 2010/02/10.

Because I really don't like having two systems and having a process
inbetween to convert from one to another (even it could be automated), i
would like to propose to get rid of the Wiki in the future.

But before getting rid of that, I have to finish a WYSIWYG editor for
restructured text, so that editing will be much easier.

PROS for getting rid of the Wiki:
-------------------------------------------
- Just one system to maintain
- Versions of the documentation could be aligned with the Dojo source code
and also tagged with the same versions
- Documentation bugs could be filed within Trac
- Bulk editing of ReST documents is much easier (search + replace)
- We could use the power of Sphinx for doing a complex TOC
- Generating PDF, when the TOC is structured better
- Not editing a large ReST document within a textarea (a doc editor could
use his favourite text editor)

CONS:
----------
- Changes are not visible immediately to everyone
- Enabling everyone to change documentation
- Generated page is visible directly after editing

For solving the two cons above I would recommend to create a new group
called "Dojo documentation contributor", that are able to commit to the
Sphinx SVN repository. All people who documented within the Wiki since a
year and those that aren't Dojo committers already will get that role, so
they will be able to make changes to the documentation. The problem with the
immediate visibility isn't solvable, but for tackling that, an automatic
generation could happen every hour. And the last con point on the list will
be solved by an WYSIWYG editor.

Until we decided that it would be good, if the Wiki is included in the Dojo
backup (Dustin?) and I will continue doing the process of converting the
Wiki to Sphinx, when there is a new Dojo version.

Regards, Tobias

2010/2/13 Marcus Reimann <marcus-nospam at dojotoolkit-forum.de>
The Wiki is good for editing and creating docs and we already have done
a lot of new docs with the current Wiki installation. So, I don't think
this will change (otherwise I would love to see a open discussion about
other solutions).

So, all we need is a Shell-Skript, which rsync with the current source
directory of the Wiki and after that, start the build-run for the static
docs. It's not voodoo, it's just a simple Shell Skript (and the
installation of rsync on the server, which was planned anyway).

Torrey, Dustin or Tobias: If you need help with this task, send me a note.

Marcus



Adam Peller wrote:
So that means we can continue making our edits on campus, for the time being?
On Fri, Feb 12, 2010 at 5:22 PM, Torrey Ricewrote:
We're working on that now and will have the answer early next week.

This version was done manually but our Phase 2 task is to make it
automated in some fashion.

On Feb 12, 2010, at 2:19 PM, Alex Russell wrote:

Hey all,

Now that the site links to static dumps of the docs, what's the
mechanism for editing? Are the exports cron'd?
_______________________________________________
dojo-contributors mailing list
dojo-contributors at mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.dojotoolkit.org/pipermail/dojo-contributors/attachments/20100215/ec6d9b18/attachment.htm

Search Discussions

Discussion Posts

Previous

Follow ups

Related Discussions

Discussion Navigation
viewthread | post
posts ‹ prev | 6 of 12 | next ›
Discussion Overview
groupdojo-contributors @
categoriesdojo
postedFeb 12, '10 at 5:19p
activeFeb 16, '10 at 3:32p
posts12
users7
websitedojotoolkit.org

People

Translate

site design / logo © 2022 Grokbase