Issue 2550907
Created on 2016-04-19 08:42 by pefu, last changed 2016-06-21 10:40 by techtonik.
Files | ||||
---|---|---|---|---|
File name | Uploaded | Description | Edit | Remove |
Roundup-issue2550907.patch | pefu, 2016-04-19 08:59 |
Messages | |||
---|---|---|---|
msg5539 | Author: [hidden] (pefu) | Date: 2016-04-19 08:42 | |
While running the command python setup.py build_doc I saw several warnings about documents not included in the table of contents: checking consistency... /home/pf/roundup-copy/doc/announcement.txt:: WARNING: document isn't included in any toctree /home/pf/roundup-copy/doc/debugging.txt:: WARNING: document isn't included in any toctree /home/pf/roundup-copy/doc/implementation.txt:: WARNING: document isn't included in any toctree /home/pf/roundup-copy/doc/mysql.txt:: WARNING: document isn't included in any toctree /home/pf/roundup-copy/doc/overview.txt:: WARNING: document isn't included in any toctree /home/pf/roundup-copy/doc/postgresql.txt:: WARNING: document isn't included in any toctree /home/pf/roundup-copy/doc/security.txt:: WARNING: document isn't included in any toctree /home/pf/roundup-copy/doc/whatsnew-0.7.txt:: WARNING: document isn't included in any toctree /home/pf/roundup-copy/doc/whatsnew-0.8.txt:: WARNING: document isn't included in any toctree done ... build succeeded, 9 warnings. I propose that we should either include these documents in index.txt or we should silence these warnings from Sphinx by adding them to the exclude_patterns list in the doc/conf.py file for Sphinx. To be more precise: My proposal is: announcement.txt : ignore in conf.py exclude_patterns debugging.txt : add to index implementation.txt : add to index mysql.txt : add to index postgresql.txt : add to index overview.txt : add to index security.txt : add to index whatsnew-0.7.txt : ignore in conf.py exclude_patterns whatsnew-0.8.txt : ignore in conf.py exclude_patterns If no one objects, I will submit a patch doing this soon. |
|||
msg5540 | Author: [hidden] (pefu) | Date: 2016-04-19 08:59 | |
see attached patch for review. Best regards, Peter Funk. |
|||
msg5561 | Author: [hidden] (techtonik) | Date: 2016-05-04 11:45 | |
On Tue, Apr 19, 2016 at 11:42 AM, Peter Funk <issues@roundup-tracker.org> wrote: > > I propose that we should either include these documents in index.txt > or we should silence these warnings from Sphinx by adding them to > the exclude_patterns list in the doc/conf.py file for Sphinx. We can always silence the warnings and comment out tests, but that drops the quality of code (or documentation in this case). Those warnings is an indication of problems with our release engineering process and with content. > To be more precise: My proposal is: > > announcement.txt : ignore in conf.py exclude_patterns > debugging.txt : add to index > implementation.txt : add to index > mysql.txt : add to index > postgresql.txt : add to index > overview.txt : add to index > security.txt : add to index Current top level is already too big, so I would think about restructuring documentation. > whatsnew-0.7.txt : ignore in conf.py exclude_patterns > whatsnew-0.8.txt : ignore in conf.py exclude_patterns Those human readable release summaries is a good start, but now look like garbage. In a perfect world these would be blog/news items with links to detailed CHANGES and UPGRADE instructions. -- anatoly t. |
|||
msg5562 | Author: [hidden] (techtonik) | Date: 2016-05-04 11:53 | |
Current top level Roundup Features Installing Roundup Upgrading to newer versions of Roundup Roundup FAQ User Guide Customising Roundup Administration Guide XML-RPC access to Roundup Design (original) Developing Roundup Roundup Tracker Templates Acknowledgements License At least this could be renamed, but I don't know if it is possible to provide separate title for ToC. Features Installation Upgrading FAQ User Guide Customising Administration Guide XML-RPC access Design (original) Development Tracker Templates Acknowledgements License There are lot of question about the docs. - FAQ looks really ancient - what is Netscape/Mozilla today? - Customizing - does it belong to User Guide or to Administration Guide? - XML-RPC access - the same - Design (original) - should it be the part of Development? |
|||
msg5563 | Author: [hidden] (pefu) | Date: 2016-05-04 12:37 | |
Hello Anatoly, > We can always silence the warnings and comment out tests, but that > drops the quality of code (or documentation in this case). I disagree: We could also remove the ancient documents from the source tree. But including out dated documentation into the index just to silence warnings would not improve the quality of the documentation. anatoly techtonik schrieb am Mittwoch, den 04.05.2016 um 14:53: > Current top level > > Roundup Features > Installing Roundup > Upgrading to newer versions of Roundup > Roundup FAQ > User Guide > Customising Roundup > Administration Guide > XML-RPC access to Roundup > Design (original) > Developing Roundup > Roundup Tracker Templates > Acknowledgements > License > > At least this could be renamed, but I don't know if it is > possible to provide separate title for ToC. This is simple: The titles for the TOC are contained in ``doc/index.txt`` and there is already one example, where an alternate TOC title line has been provided: The original design.txt is currently overwritten this the text "Roundup - An Issue-Tracking System for Knowledge Workers" which is renamed in the TOC (index.txt). ... [off-topic]: > There are lot of question about the docs. > - FAQ looks really ancient - what is Netscape/Mozilla today? > - Customizing - does it belong to User Guide or to Administration Guide? > - XML-RPC access - the same > - Design (original) - should it be the part of Development? Please open new issues and whenever your time permits contribute patches solving any issues you have with the overall TOC structure. Best regards, Peter. |
|||
msg5579 | Author: [hidden] (rouilj) | Date: 2016-06-05 06:01 | |
Hi Peter: Looking at the security mechanisms doc, I think that doc is obsolete. I suggest ignoring and not including it in the built docs. The last substantive change to it was in 2007. If you are ok with that suggestion I can commit this patch. Then we can entertain other patches to re-org the docs. |
|||
msg5587 | Author: [hidden] (rouilj) | Date: 2016-06-11 01:30 | |
applied patch with change to ignore obsolete security.txt. |
|||
msg5616 | Author: [hidden] (techtonik) | Date: 2016-06-21 10:40 | |
On Wed, May 4, 2016 at 3:37 PM, Peter Funk <issues@roundup-tracker.org> wrote: >> We can always silence the warnings and comment out tests, but that >> drops the quality of code (or documentation in this case). > > I disagree: We could also remove the ancient documents from the > source tree. But including out dated documentation into the index > just to silence warnings would not improve the quality of the documentation. There is no conflict here. Documentation is for users, so keeping outdated stuff is only important for software archaeology, and that story is pretty well solved by http://web.archive.org/web/20160327204611/http://www.roundup-tracker.org/docs.html So I am +1 on cleaning up the stuff. |
History | |||
---|---|---|---|
Date | User | Action | Args |
2016-06-21 10:40:05 | techtonik | set | messages: + msg5616 |
2016-06-11 01:30:07 | rouilj | set | status: new -> closed resolution: fixed messages: + msg5587 |
2016-06-05 06:01:23 | rouilj | set | nosy:
+ rouilj messages: + msg5579 |
2016-05-04 12:37:11 | pefu | set | type: rfe messages: + msg5563 components: + Documentation versions: + 1.5 |
2016-05-04 11:53:46 | techtonik | set | messages: + msg5562 |
2016-05-04 11:45:11 | techtonik | set | nosy:
+ techtonik messages: + msg5561 |
2016-04-19 08:59:39 | pefu | set | files:
+ Roundup-issue2550907.patch keywords: + patch messages: + msg5540 |
2016-04-19 08:42:18 | pefu | create |