Hi everyone,<br><br>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 <a href="http://livedocs.dojotoolkit.org">livedocs.dojotoolkit.org</a> is transferred to the statically generated reference-guide.<br>
<br>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, ...):<br><br>Wiki<br>------<br>
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.<br><br>Sphinx (static generation)<br>-----------------------------------<br>The other system is the respository at <a href="http://svn.dojotoolkit.org/dojo_doc_wiki/">http://svn.dojotoolkit.org/dojo_doc_wiki/</a> where we are using the documentation system Sphinx (<a href="http://sphinx.pocoo.org/">http://sphinx.pocoo.org/</a>: written in Python and it is also used for writing the Python documentation) for generating the static documentation you currently see at <a href="http://dojotoolkit.org/reference-guide">http://dojotoolkit.org/reference-guide</a>.<br>
<br><br>For creating the static documentation I currently copy the &quot;pages&quot; directory of the wiki and use the script <a href="http://svn.dojotoolkit.org/dojo_doc_wiki/_addon/moinconverter.py">http://svn.dojotoolkit.org/dojo_doc_wiki/_addon/moinconverter.py</a> 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.<br>
<br>That is because:<br>- Both systems use a different method for linking<br>- Sphinx has a concept for generating a Table-Of-Content<br><br>Since release 1.3 I do this process for every new Dojo release and I did the last conversion at 2010/02/10. <br>
<br>Because I really don&#39;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.<br><br>But before getting rid of that, I have to finish a WYSIWYG editor for restructured text, so that editing will be much easier.<br>
<br>PROS for getting rid of the Wiki:<br>-------------------------------------------<br>- Just one system to maintain<br>- Versions of the documentation could be aligned with the Dojo source code and also tagged with the same versions<br>
- Documentation bugs could be filed within Trac<br>- Bulk editing of ReST documents is much easier (search + replace)<br>- We could use the power of Sphinx for doing a complex TOC<br>- Generating PDF, when the TOC is structured better<br>
- Not editing a large ReST document within a textarea (a doc editor could use his favourite text editor)<br><br>CONS:<br>----------<br>- Changes are not visible immediately to everyone<br>- Enabling everyone to change documentation<br>
- Generated page is visible directly after editing<br><br>For solving the two cons above I would recommend to create a new group called &quot;Dojo documentation contributor&quot;, that are able to commit to the Sphinx SVN repository. All people who documented within the Wiki since a year and those that aren&#39;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&#39;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.<br>
<br>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.<br><br>Regards, Tobias<br>
<br><div class="gmail_quote">2010/2/13 Marcus Reimann <span dir="ltr">&lt;<a href="mailto:marcus-nospam@dojotoolkit-forum.de">marcus-nospam@dojotoolkit-forum.de</a>&gt;</span><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
The Wiki is good for editing and creating docs and we already have done<br>
a lot of new docs with the current Wiki installation. So, I don&#39;t think<br>
this will change (otherwise I would love to see a open discussion about<br>
other solutions).<br>
<br>
So, all we need is a Shell-Skript, which rsync with the current source<br>
directory of the Wiki and after that, start the build-run for the static<br>
docs. It&#39;s not voodoo, it&#39;s just a simple Shell Skript (and the<br>
installation of rsync on the server, which was planned anyway).<br>
<br>
Torrey, Dustin or Tobias: If you need help with this task, send me a note.<br>
<font color="#888888"><br>
Marcus<br>
</font><div class="im"><br>
<br>
<br>
Adam Peller wrote:<br>
&gt; So that means we can continue making our edits on campus, for the time being?<br>
&gt;<br>
&gt; On Fri, Feb 12, 2010 at 5:22 PM, Torrey Rice&lt;<a href="mailto:itorrey@gmail.com">itorrey@gmail.com</a>&gt;  wrote:<br>
&gt;<br>
&gt;&gt; We&#39;re working on that now and will have the answer early next week.<br>
&gt;&gt;<br>
&gt;&gt; This version was done manually but our Phase 2 task is to make it automated in some fashion.<br>
&gt;&gt;<br>
&gt;&gt;<br>
&gt;&gt; On Feb 12, 2010, at 2:19 PM, Alex Russell wrote:<br>
&gt;&gt;<br>
&gt;&gt;<br>
&gt;&gt;&gt; Hey all,<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; Now that the site links to static dumps of the docs, what&#39;s the<br>
&gt;&gt;&gt; mechanism for editing? Are the exports cron&#39;d?<br>
&gt;&gt;&gt;<br>
</div><div><div></div><div class="h5">_______________________________________________<br>
dojo-contributors mailing list<br>
<a href="mailto:dojo-contributors@mail.dojotoolkit.org">dojo-contributors@mail.dojotoolkit.org</a><br>
<a href="http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors" target="_blank">http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors</a><br>
</div></div></blockquote></div><br>