Roundup Tracker - Issues

Issue 2550498

classification
Rework documentation generation
Type: behavior Severity: major
Components: Infrastructure Versions: devel
process
Status: closed fixed
:
: stefan : richard, stefan
Priority: :

Created on 2009-02-06 17:14 by stefan, last changed 2009-02-16 21:12 by stefan.

Files
File name Uploaded Description Edit Remove
roundup-docs.tgz stefan, 2009-02-07 14:10
Messages
msg3518 Author: [hidden] (stefan) Date: 2009-02-06 17:14
I would like to rework how Roundup's documentation is compiled to HTML.
The goal is to a) make this process compatible with the new website and
b) prepare it to be installed / packaged with the rest.

The website is built with sphinx (http://sphinx.pocoo.org/), and so
would the the Roundup docs.

There are two sets of changes to get this:

1) Added build infrastructure to build, install, and package those docs
2) Adjustments to the documentation source files

If this sounds OK, I can either submit those patches, or check them in
right away.
msg3519 Author: [hidden] (richard) Date: 2009-02-06 22:03
On Sat, Feb 7, 2009 at 4:14 AM, Stefan Seefeld
<issues@roundup-tracker.org> wrote:
> I would like to rework how Roundup's documentation is compiled to HTML.
> The goal is to a) make this process compatible with the new website and
> b) prepare it to be installed / packaged with the rest.

Exactly what will this change? Will files be renamed or moved? As
already discussed I'd like for the existing URLs to remain working.

      Richard
msg3520 Author: [hidden] (stefan) Date: 2009-02-06 22:09
Richard Jones wrote:

> Exactly what will this change? Will files be renamed or moved? As
> already discussed I'd like for the existing URLs to remain working.

I'm talking about $roundup/doc/*.html, i.e. the html files that are 
built when I call 'make' in that directory. Are they referencable via 
URLs at all ? They don't seem to get installed or packaged.

(I was going to suggest to install them into 
<prefix>/share/doc/roundup-<version>/html/)

Thanks,
		Stefan
msg3522 Author: [hidden] (stefan) Date: 2009-02-07 14:10
I have attached a tarball containing the newly generated HTML, together
with a reworked doc/index.txt. All the other sources were unchanged.
If you prefer the html to be right in doc/, that can certainly be done
(though I don't see why that would be useful).

As I mentioned, I use sphinx to generate this, with a template slightly
different from the one I used for the website. That can all be fine-tuned...

The idea is to make all the docs (online and offline) be as similar and
easy to maintain as possible.

Comments welcome !
msg3523 Author: [hidden] (richard) Date: 2009-02-07 20:50
I was referring to how that HTML was available on the Roundup website.
I have no objection to installing it under /usr/share/doc but not that
OS X and Windows have no similar facility that I'm aware of.
msg3524 Author: [hidden] (stefan) Date: 2009-02-07 21:00
Richard Jones wrote:
> Richard Jones <richard@mechanicalcat.net> added the comment:
> 
> I was referring to how that HTML was available on the Roundup website.
> I have no objection to installing it under /usr/share/doc but not that
> OS X and Windows have no similar facility that I'm aware of.

Oh, then we have been talking past each other a little. :-)

Let me try to summarize how things look from my end:

We have two sets of end-user docs: the website, and the docs that are 
part of the Roundup installation. They overlap considerably, and thus 
are mostly built from the same sources (roundup/doc/).
The generated HTML, however, differs, at least in the navigational 
elements: The website has a menu, while the docs present a 'document 
structure' with 'next'/'previous'/'up' links on each page.

The website wouldn't be installed anywhere other than, well, on the 
website. What I propose to install is the docs (see the attachment of my 
last mail). I'm not sure where docs would end up on Windows / OSX. I'm 
sure we can find precedence in other Python packages that ship 
documentation.

Does this make sense ?

Thanks,
		Stefan
msg3534 Author: [hidden] (richard) Date: 2009-02-12 01:56
This sounds fine. No installation is necessary on OS X and Windows, as
long as the doc .txt are shipped with Roundup the text files are there
for people to turn to.
msg3541 Author: [hidden] (stefan) Date: 2009-02-12 06:01
Richard Jones wrote:

> This sounds fine. No installation is necessary on OS X and Windows, as
> long as the doc .txt are shipped with Roundup the text files are there
> for people to turn to.

I have just checked in a patch for this (revision 4124). To generate 
documentation, run 'python setup.py build_doc', which should generate 
share/doc/roundup/.

Now that both the website and the documentation use the same build 
logic, I'm able to clean up the documentation sources a little (for 
example, take out some now obsolete links).

Then I will simplify the website regeneration, as it uses some of the 
sources from the roundup docs.

Feedback on the new documentation layout is welcome !

		Stefan
History
Date User Action Args
2009-02-16 21:12:19stefansetstatus: new -> closed
resolution: fixed
2009-02-12 06:01:17stefansetmessages: + msg3541
2009-02-12 01:56:19richardsetmessages: + msg3534
2009-02-07 21:00:51stefansetmessages: + msg3524
2009-02-07 20:50:31richardsetmessages: + msg3523
2009-02-07 14:10:24stefansetfiles: + roundup-docs.tgz
messages: + msg3522
2009-02-06 22:09:18stefansetmessages: + msg3520
2009-02-06 22:03:03richardsetmessages: + msg3519
2009-02-06 17:14:56stefancreate