Issue 9783

Title
Remove toctree from README.rst files
Priority
feature
Status
resolved
Nosy list
ced, dave, reviewbot, roundup-bot
Assigned to
dave
Keywords
Documentation, review

Created on 2020-11-03.11:35:07 by dave, last changed 2 months ago by roundup-bot.

Messages

New changeset 41ffe478a57d by David Harper in branch 'default':
Strip toctree using a regular expression
https://hg.tryton.org/cookiecutter/rev/41ffe478a57d
Author: [hidden] (dave) Tryton committer
Date: 2020-11-16.11:21:27

Yes, I agree, that sounds like a sensible suggestion.

Author: [hidden] (ced) Tryton committer Tryton translator
Date: 2020-11-15.14:46:10

I propose to first update only cookiecutter and to apply this change when each module receive the new documentation structure.

Author: [hidden] (dave) Tryton committer
Date: 2020-11-03.13:17:01

I've just found issue8465, which already removes the toctree using a slice. I propose to change this to a regular expression, so that we do not have to update the setup.py file if the toctrees in the documentation change.

Author: [hidden] (dave) Tryton committer
Date: 2020-11-03.12:09:09

I do like the idea of stripping out the Sphinx syntax out using the read method.

To keep it as simple as possible I think we should limit it to just removing the toctree directive, and then just make sure we don't include any other Sphinx markup in doc/index.rst (enforced by issue9781).

Author: [hidden] (ced) Tryton committer Tryton translator
Date: 2020-11-03.11:54:59

I think it will be confusing for the user to have such track path to read the documentation. One of the goal of using reStructuredText is to be easily readable in the source.
What about having the read method in setup.py to strip Sphinx syntax marks?

Author: [hidden] (dave) Tryton committer
Date: 2020-11-03.11:35:05

The README.rst files are used on PyPI, and they should only contain standard reStructuredText markup and directives. At the moment some of the modules (such as the timesheet module) use the toctree directive in the doc/index.rst file which is used as the README.rst file, although it may seem to work it is not supported.

To fix this we could move the doc/index.rst file to README.rst, and remove any toctree and other Sphinx specific markup from it. Then create a doc/index.rst file that contains for example:

.. include:: ../README.rst

.. toctree::
    :maxdepth: 1

    user_application
History
Date User Action Args
2020-12-05 15:25:41roundup-botsetmessages: + msg62438
nosy: + roundup-bot
status: testing -> resolved
2020-11-16 11:21:27davesetmessages: + msg61961
2020-11-15 14:46:10cedsetmessages: + msg61929
2020-11-13 16:52:40davesetstatus: in-progress -> testing
2020-11-03 14:41:44reviewbotsetmessages: + msg61619
2020-11-03 13:39:01reviewbotsetmessages: + msg61613
nosy: + reviewbot
2020-11-03 13:39:01reviewbotsetkeyword: + review
reviews: 314741002
2020-11-03 13:17:01davesetmessages: + msg61612
2020-11-03 12:09:09davesetmessages: + msg61609
2020-11-03 11:54:59cedsetmessages: + msg61606
nosy: + ced

Showing 10 items. Show all history (warning: this could be VERY long)