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 https://hg.tryton.org/cookiecutter/rev/41ffe478a57d
Yes, I agree, that sounds like a sensible suggestion.
I propose to first update only cookiecutter and to apply this change when each module receive the new documentation structure.
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.
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).
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?
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
nosy: + roundup-bot
status: testing -> resolved
|2020-11-16 11:21:27||dave||set||messages: + msg61961|
|2020-11-15 14:46:10||ced||set||messages: + msg61929|
|2020-11-13 16:52:40||dave||set||status: in-progress -> testing|
|2020-11-03 14:41:44||reviewbot||set||messages: + msg61619|
nosy: + reviewbot
|2020-11-03 13:17:01||dave||set||messages: + msg61612|
|2020-11-03 12:09:09||dave||set||messages: + msg61609|
nosy: + ced
Showing 10 items. Show all history (warning: this could be VERY long)