Issue 9783

Remove toctree from README.rst files
Nosy list
ced, dave, reviewbot, roundup-bot
Assigned to
Documentation, review

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


New changeset 41ffe478a57d by David Harper in branch 'default':
Strip toctree using a regular expression
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 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 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

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)