> * The BODY section should be a single paragraph of English text in ReST format. It should not use the following ReST markup features: > * section headers > * comments > * directives, citations, or footnotes > * Any features that require significant line breaks, like lists, definition lists, quoted paragraphs, line blocks, literal code blocks, and tables.
As far as I can tell, the usage of inline markup for links with something like :func:\`os.listdir\` would not be in violation of this. Also, as a clarification, what I was describing was apparently just Sphinx, not reST: https://devguide.python.org/documenting/#id4. For some reason, I was under the impression that the syntax was reST and then Sphinx processed the markup to find a matching link. I'm not certain as to whether or not blurb supports Sphinx. If not, I wouldn't mind assisting with the process of adding support for it, I think it's worthwhile to include inline links when appropriate. If not, the link could also be provided with the reST cross-link markup: :ref:\`label\` as long as the section has a corresponding label. This doesn't seem like it uses any of the above restricted reST features. But if that's also an issue, a more explicit reST hyper link could be provided with: \`Link text < http://target>\`_. However, direct links are probably the most likely to become deprecated or lead to dead ends, so the other options would be more preferable for less maintenance. Thanks, Kyle Stanley On Tue, Aug 13, 2019 at 2:41 AM Mariatta <mariatta.wij...@gmail.com> wrote: > > I would like to understand why some developers dislike including it, > even when the reST syntax is provided. > > This has something to do with the use of blurb/blurb-it. Both tools > specifically say "single paragraph with simple ReST markup". > > Further reading blurb's source code, it says the format of the news blurb > should be as follows: > > * The BODY section should be a single paragraph of English text > in ReST format. It should not use the following ReST markup > features: > * section headers > * comments > * directives, citations, or footnotes > * Any features that require significant line breaks, > like lists, definition lists, quoted paragraphs, line blocks, > literal code blocks, and tables. > > > Perhaps Larry has more context on why the news entry should be "simple"? > > >
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/YTST7DKDTD3K6PIUE345J25B2CMJORLY/
