Issue 2550498
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:19 | stefan | set | status: new -> closed resolution: fixed |
2009-02-12 06:01:17 | stefan | set | messages: + msg3541 |
2009-02-12 01:56:19 | richard | set | messages: + msg3534 |
2009-02-07 21:00:51 | stefan | set | messages: + msg3524 |
2009-02-07 20:50:31 | richard | set | messages: + msg3523 |
2009-02-07 14:10:24 | stefan | set | files:
+ roundup-docs.tgz messages: + msg3522 |
2009-02-06 22:09:18 | stefan | set | messages: + msg3520 |
2009-02-06 22:03:03 | richard | set | messages: + msg3519 |
2009-02-06 17:14:56 | stefan | create |