Roundup Tracker - Issues

Issue 2550774

classification
Minor documentation fixes
Type: Severity: minor
Components: Documentation Versions: 1.4
process
Status: closed
:
: : ber, jerrykan, kai
Priority: : patch

Created on 2012-09-05 20:21 by kai, last changed 2012-12-16 11:32 by jerrykan.

Files
File name Uploaded Description Edit Remove
documentation.patch kai, 2012-09-05 20:21
Messages
msg4640 Author: [hidden] (kai) Date: 2012-09-05 20:21
I've patched a few things some minor nuisances. I've discussed this on
the mailinglist. (subject: "doc/conf.py and doc/Makefile")

The problems:
* cannot regenerate the html version of the docs from the release tarball
  (as documented in the README.txt)
* cannot "make html" in website/www dir

I've fixed the README, removed the useless doc/Makefile, and fixed the
website/www/Makefile to make it indempotent.


Regards,
Kai Storbeck
msg4654 Author: [hidden] (jerrykan) Date: 2012-09-30 09:43
Hello Kai,

The first part of the patch (regenerate the html version of the docs)
looks good to me. It looks like the rst2html stuff is no longer
relevant, so removing the Makefile and updating the README.txt makes
sense. I would be happy to commit that part of the patch as it is, but I
will wait a few more days to see if anyone else has anything to add.


I think the part to do with the 'website/www' is a good start, but might
need a bit more work before committing the changes:

 - Creating a symlink for 'COPYING.txt' makes the error go away, but the
link in 'license.txt' to 'COPYING.txt' doesn't actually show up in the
generated html (so this should probably be fixed as well).

 - I'm not sure if the 'COPYING.txt' file was intended to be processed
by Sphinx, so it might be worth seeing if 'make' can skip processing the
file but still link to it as a plain text file.

 - During the 'make clean' command, if we are leaving the 'html/'
directory in place then we probably want to leave the 'COPYING.txt' file
in place as well; seeing as though it will be linked too (ie. delete
only the intermediate files). Alternatively if we want to remove the
'COPYING.txt' file we should also remove the 'html/' directory (ie.
delete all generated files). I'm not sure which is the convention for
'make clean' (delete all generated files or just intermediate files)


On a semi-related note, personally I would also split this up into two
separate patches/issues (ie. one patch/commit per fix). This isn't
necessarily a convention of the project, but I find much easier to
review small concise patches, and I'm more likely to commit changes if
it doesn't take a lot of effort on my part :D
msg4655 Author: [hidden] (kai) Date: 2012-10-09 22:09
Hi John,

John Kristensen wrote:
> John Kristensen added the comment:
> 
> Hello Kai,

Thanks for getting back on this.

> The first part of the patch (regenerate the html version of the docs)
> looks good to me. It looks like the rst2html stuff is no longer
> relevant, so removing the Makefile and updating the README.txt makes
> sense. I would be happy to commit that part of the patch as it is, but I
> will wait a few more days to see if anyone else has anything to add.

Good.

> I think the part to do with the 'website/www' is a good start, but might
> need a bit more work before committing the changes:
> 
>  - Creating a symlink for 'COPYING.txt' makes the error go away, but the
> link in 'license.txt' to 'COPYING.txt' doesn't actually show up in the
> generated html (so this should probably be fixed as well).

Ah. But thats part of the documentation, not the website. The docs get
"symlinked" into the website. You will encounter a link to the license
from the subdir 'doc/index.html'.

>  - I'm not sure if the 'COPYING.txt' file was intended to be processed
> by Sphinx, so it might be worth seeing if 'make' can skip processing the
> file but still link to it as a plain text file.

See previous comment; Its there because license.txt includes it.

>  - During the 'make clean' command, if we are leaving the 'html/'
> directory in place then we probably want to leave the 'COPYING.txt' file
> in place as well; seeing as though it will be linked too (ie. delete
> only the intermediate files). Alternatively if we want to remove the
> 'COPYING.txt' file we should also remove the 'html/' directory (ie.
> delete all generated files). I'm not sure which is the convention for
> 'make clean' (delete all generated files or just intermediate files)

Good point. I'll fix the clean target to remove $(HTML) too.

> On a semi-related note, personally I would also split this up into two
> separate patches/issues (ie. one patch/commit per fix). This isn't
> necessarily a convention of the project, but I find much easier to
> review small concise patches, and I'm more likely to commit changes if
> it doesn't take a lot of effort on my part :D

I can see your point. My fix is the fastest way to get it working again.
I'll be crafting a shorter commit soon.

Cheers,
Kai
msg4666 Author: [hidden] (jerrykan) Date: 2012-11-02 06:03
On 10/10/12 09:09, Kai Storbeck wrote:
>> I think the part to do with the 'website/www' is a good start, but might
>> need a bit more work before committing the changes:
>>
>>   - Creating a symlink for 'COPYING.txt' makes the error go away, but the
>> link in 'license.txt' to 'COPYING.txt' doesn't actually show up in the
>> generated html (so this should probably be fixed as well).
>
> Ah. But thats part of the documentation, not the website. The docs get
> "symlinked" into the website. You will encounter a link to the license
> from the subdir 'doc/index.html'.

The documentation and the website docs are one ad the same (hence the 
symlinking). If you go to:
   http://www.roundup-tracker.org/docs/license.html
you will see that it is referring to the COPYING.txt file, but there is 
nothing there.

>
>>   - I'm not sure if the 'COPYING.txt' file was intended to be processed
>> by Sphinx, so it might be worth seeing if 'make' can skip processing the
>> file but still link to it as a plain text file.
>
> See previous comment; Its there because license.txt includes it.
>

I assume the text of COPYING.txt is supposed to be included in the 
license.html page (see above), though I am not sure if Sphinx can do 
this. At the least license.html should probably link to a copy of 
COPYING.txt
msg4692 Author: [hidden] (ber) Date: 2012-12-14 07:56
John wrote (on -devel) that he is going to clean up here a little bit
and commit for the next release, which is cool!

He also wrote:
> I will try to clean it up a bit and commit it in the coming days. If
> someone with a bit of knowledge about sphinx wants to comment on how
> best to fix the referencing of the COPYING.txt file/text it would be
> appreciated.

Last time I looked at it, the issue was that there were two places
the stuff was build from. I agree we should make both of them sphinx.
msg4700 Author: [hidden] (jerrykan) Date: 2012-12-16 11:32
I just tested the generation of the website documentation and the
contents of COPYING.txt is now included in the resulting license.html
file (I'm not sure why this wasn't working for me before).

The changes have now been committed, with a couple of minor changes (ie.
removing the 'html/' directory on clean).

Thanks for the patch Kai, and apologies for the delay in getting it
committed.
History
Date User Action Args
2012-12-16 11:32:19jerrykansetstatus: new -> closed
messages: + msg4700
2012-12-14 07:56:21bersetnosy: + ber
messages: + msg4692
2012-11-02 06:03:36jerrykansetmessages: + msg4666
2012-10-09 22:09:55kaisetmessages: + msg4655
2012-09-30 09:43:13jerrykansetnosy: + jerrykan
messages: + msg4654
2012-09-05 20:21:10kaicreate