Doc tool for us!

[Mark Ramm]

http://sphinx.pocoo.org/index.html

This seems to be the place to go for ReST doc handling. It seems to
do everything we need it to do, and do it well.

--
Mark Ramm-Christensen
email: mark at compoundthinking dot com
blog: www.compoundthinking.com/blog

[Kevin Horn]

Oh wow...that look s EXTREMELY nice.

Kevin Horn

[Chris Arndt]

Yes, I also had a look at this tool and even had a go at feeding it
with the current documentation on the wiki. The output looks indeed
very nice and should make a good way to generate an offline
distribution of the docs.

There is ome work necessary to complete the conversion, most of which
can be automized:

- The toc marker neds to removed from every page
- The comment markup needs to be removed from every page
- "toctree" pages need to be written for every collection of
documents*
- (Optional) mark up class/function/file names etc. to eable automatic
referencing.

* This is a manual process and the main work, as we ned to identify
the documents to include, sort them into collections (i.e. like
"books") and put them in proper order.

Sphinx also has a directive for inlcuding code examples from external
files, so this might also be a starting point for a tutorial
generating tool like it is outlined on the GSoC ideas page.

I'll try to upload my results with converting the current wiki docs
somewhere asap.

Chris

[gas...@gmail.com]

Hi,

I upload a modified script get_tgdoc.py to trac
http://trac.turbogears.org/ticket/34

It could:

* download rst docs (2.0, can be specified for other version)
* replace <2.0/....>_ links to <....>_


To work with sphinx,

1. generated default doc framework by 'sphinx-quickstart' command,
2. place 'get_tgdoc.py' into source folder
3. run 'python get_tgdoc.py' to get rst sources
4. add '2.0/indx' and '2.0/RoughDocs' to index.rst
5. run 'make html'

Then there's a rough html doc available.

--
Fred

[Kevin Horn]

I get the following traceback when running get_tgdoc.py on WinXP (Py 2.5)

C:\Documents and Settings\khorn\Desktop\mine_scs\tg2_doc_test\source>get_tgdoc.py
download http://docs.turbogears.org/2.0?action=raw
Traceback (most recent call last):
  File "C:\Documents and Settings\khorn\Desktop\mine_scs\tg2_doc_test\source\get_tgdoc.py", line 150, in <module>
    process_docs(targets)
  File "C:\Documents and Settings\khorn\Desktop\mine_scs\tg2_doc_test\source\get_tgdoc.py", line 140, in process_docs
    proc_doc(link, doc, targets)
  File "C:\Documents and Settings\khorn\Desktop\mine_scs\tg2_doc_test\source\get_tgdoc.py", line 117, in proc_doc
    for doclink in extra:
NameError: global name 'extra' is not defined

What is "extra"?

Kevin Horn

[gas...@gmail.com]

> Settings\khorn\Desktop\mine_scs\tg2_doc_test\source\get_tgdoc.py", line 117,
> in proc_doc
>     for doclink in extra:
> NameError: global name 'extra' is not defined
>
> What is "extra"?
>
> Kevin Horn

Please remove these 2 lines::

for doclink in extra:
doc = doc.replace("/"+doclink, doclink)

Then the script will work

[Kevin Horn]

On Tue, Mar 25, 2008 at 1:29 AM, gas...@gmail.com <gas...@gmail.com> wrote:

Fred,

Can you explain step 4 in a little more detail?  Where and how should those be added?

Kevin Horn

[Kevin Horn]

Thanks, Fred.  Download script works fr me now.

Kevin Horn

[gas...@gmail.com]

> > To work with sphinx,
>
> > 1. generated default doc framework by 'sphinx-quickstart' command,
> > 2. place 'get_tgdoc.py' into source folder
> > 3. run 'python get_tgdoc.py' to get rst sources
> > 4. add '2.0/indx' and '2.0/RoughDocs' to index.rst
> > 5. run 'make html'
>
> > Then there's a rough html doc available.
>
> > --
> > Fred
>
> Fred,
>
> Can you explain step 4 in a little more detail?  Where and how should those
> be added?
>
> Kevin Horn

Mmm... now it is simple::

1. Check out tg2 trunk
2. enter 'docs' folder
3. type 'python get_tgdoc.py' (to fetch rst docs)
4. type 'make html' (to generate docs)
5. enter '_build' folder, open 'index.html'

I found a bug(?) that sphinx won't add 'html' automatically after each
wiki links.

Thus when I click 'DownloadInstall' link, I'll be redirected to
'DownloadInstall', but not 'DownloadInstall.html'.

--
Fred

[Christopher Arndt]

gasolin-Re5JQEe...@public.gmane.org schrieb:

> I found a bug(?) that sphinx won't add 'html' automatically after each
> wiki links.

You need to include all pages in a "toctree" (check the sphinx docs) for
the internal links to work properly.

Chris