Issue 2550774
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:19 | jerrykan | set | status: new -> closed messages: + msg4700 |
2012-12-14 07:56:21 | ber | set | nosy:
+ ber messages: + msg4692 |
2012-11-02 06:03:36 | jerrykan | set | messages: + msg4666 |
2012-10-09 22:09:55 | kai | set | messages: + msg4655 |
2012-09-30 09:43:13 | jerrykan | set | nosy:
+ jerrykan messages: + msg4654 |
2012-09-05 20:21:10 | kai | create |