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.

see attached patch for review.

Best regards, Peter Funk.

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.

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?

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.

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.

applied patch with change to ignore obsolete security.txt.

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.