<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
  <title></title>
</head>
<body bgcolor="#ffffff" text="#000000">
I'm confused, livedocs.dojotoolkit.org is just a rename of
docs.dojotoolkit.org, right?&nbsp;&nbsp; I thought everything was already working
automatically, because on docs.dojotoolkit.org I can see the page as
soon as I hit the save button.&nbsp;&nbsp;&nbsp; Why do you need code converting from
the dojo rest format into sphinx format?&nbsp;&nbsp; I can understand wanting to
make a static copy of the doc, but can't you just copy the HTML from
docs.dojotoolkit.org?<br>
<br>
Tobias Klipstein wrote:
<blockquote
 cite="mid:5516141c1002150921v3b870db8hc2c01a07c903811e@mail.gmail.com"
 type="cite">
  <meta http-equiv="Context-Type"
 content="text/html; charset=ISO-8859-1">
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
 moz-do-not-send="true" 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.&nbsp; .. 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 moz-do-not-send="true"
 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
 moz-do-not-send="true" 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 moz-do-not-send="true"
 href="http://dojotoolkit.org/reference-guide">http://dojotoolkit.org/reference-guide</a>.<br>
  <br>
  <br>
For creating the static documentation I currently copy the "pages"
directory of the wiki and use the script <a moz-do-not-send="true"
 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'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 "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.<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>2010/2/13 Marcus Reimann <span>&lt;<a moz-do-not-send="true"
 href="mailto:marcus-nospam@dojotoolkit-forum.de">marcus-nospam@dojotoolkit-forum.de</a>&gt;</span><br>
  <blockquote>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'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's not voodoo, it'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>
    <br>
Marcus<br>
    <div><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
 moz-do-not-send="true" href="mailto:itorrey@gmail.com">itorrey@gmail.com</a>&gt;
&nbsp;wrote:<br>
&gt;<br>
&gt;&gt; We'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's the<br>
&gt;&gt;&gt; mechanism for editing? Are the exports cron'd?<br>
&gt;&gt;&gt;<br>
    </div>
    <div>
    <div>_______________________________________________<br>
dojo-contributors mailing list<br>
    <a moz-do-not-send="true"
 href="mailto:dojo-contributors@mail.dojotoolkit.org">dojo-contributors@mail.dojotoolkit.org</a><br>
    <a moz-do-not-send="true"
 href="http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors">http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors</a><br>
    </div>
    </div>
  </blockquote>
  </div>
  <br>
  <pre wrap="">
<hr size="4" width="90%">
_______________________________________________
dojo-contributors mailing list
<a class="moz-txt-link-abbreviated" href="mailto:dojo-contributors@mail.dojotoolkit.org">dojo-contributors@mail.dojotoolkit.org</a>
<a class="moz-txt-link-freetext" href="http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors">http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors</a>
  </pre>
</blockquote>
</body>
</html>