provide a .md template alongside the .rst one #94
Conversation
There was a problem hiding this comment.
Yes please! See also #85.
Here are minor tweaks I’d recommend, and a suggestion to also drop the forced line wrapping at 80 characters so the content is more readable.
| (the same format as Django's documentation). | ||
| DEPs may be written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ | ||
| (the same format as Django's documentation) or | ||
| `MarkDown <https://www.markdownguide.org>` (the same as GitHub issues). | ||
|
|
||
| Each DEP should have the following parts: |
There was a problem hiding this comment.
I think it’d be worth updating the point about preambles below. Perhaps just removing the specifics:
A preamble -- metadata about the DEP […]
| conjunction with the content guidelines in [DEP | ||
| 1](https://github.com/django/deps/final/0001-dep-process.rst), this | ||
| should make it easy for you to conform your own DEPs to the format | ||
| outlined below. |
There was a problem hiding this comment.
In #85 there’s also a mention of removing the wrapping to 80 characters, what do you think of updating this template accordingly?
| TEMPLATE!** | ||
|
|
||
| To get the source this (or any) DEP, look at the top of the Github page | ||
| and click \"raw\". |
There was a problem hiding this comment.
Here and further through the rest of the doc, I think it’d be nice to remove the unnecessary escaping.
Co-authored-by: Thibaud Colas <[email protected]>
|
@thibaudcolas I'm personally in favour of everything mentioned in #85 and the original list but since none of those seemed to have reached a consensus, my goal for this PR was to be as minimal as possible in order to be able to merge it as quick as possible. If we can get a strong support behind all those changes, I'd be more than happy to have it here. Then I would also suggest removing the manual TOC in the .md file since, GitHub has this out of the box as a dropdown. |
Co-authored-by: Thibaud Colas <[email protected]>
Which part? the part about not doing more in this particular PR or the part about doing more? |
|
the part about keeping things simple until there’s more support :) |
| (the same format as Django's documentation). | ||
| DEPs may be written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ | ||
| (the same format as Django's documentation) or | ||
| `Markdown <https://www.markdownguide.org>` (the same as GitHub issues). |
There was a problem hiding this comment.
| `Markdown <https://www.markdownguide.org>` (the same as GitHub issues). | |
| `Markdown <https://www.markdownguide.org>`_ (the same as GitHub issues). |
| the names of the various members of the `DEP team <#forming- the-team>`_, and so forth. | ||
| See `DEP Metadata`_ below for specific details. | ||
| This can be provided as a rST `field list <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists>`_ | ||
| or MarkDown frontmatter `https://github.com/Kernix13/markdown-cheatsheet/blob/master/frontmatter.md`_ |
There was a problem hiding this comment.
| or MarkDown frontmatter `https://github.com/Kernix13/markdown-cheatsheet/blob/master/frontmatter.md`_ | |
| or `Markdown frontmatter <https://github.com/Kernix13/markdown-cheatsheet/blob/master/frontmatter.md>`_ |
| See `DEP Metadata`_ below for specific details. | ||
| This can be provided as a rST `field list <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists>`_ | ||
| or MarkDown frontmatter `https://github.com/Kernix13/markdown-cheatsheet/blob/master/frontmatter.md`_ | ||
| depending on which temaplte you are using. |
There was a problem hiding this comment.
| depending on which temaplte you are using. | |
| depending on which template you are using. |
| To get the source this (or any) DEP, look at the top of the Github page | ||
| and click \"raw\". | ||
|
|
||
| If you\'re unfamiliar with MarkDown, this template also exists |
There was a problem hiding this comment.
| If you\'re unfamiliar with MarkDown, this template also exists | |
| If you\'re unfamiliar with Markdown, this template also exists |
| __ http://docutils.sourceforge.net/docs/rst/quickref.html | ||
| __ http://docutils.sourceforge.net/spec/rst/reStructuredText.html | ||
| If you're unfamiliar with reStructuredText, this template also exists as a | ||
| `MarkDown template <./template.md>`_. |
There was a problem hiding this comment.
| `MarkDown template <./template.md>`_. | |
| `Markdown template <./template.md>`_. |
|
|
||
| Note: if you are reading this DEP via the web, you should first grab | ||
| [the source of this | ||
| DEP](https://raw.githubusercontent.com/django/deps/refs/heads/main/template.rst) in |
There was a problem hiding this comment.
Maybe this should link to the Markdown template?
| DEP](https://raw.githubusercontent.com/django/deps/refs/heads/main/template.rst) in | |
| DEP](https://raw.githubusercontent.com/django/deps/refs/heads/main/template.md) in |
As suggested in this forum thread and this mastodon thread and probably many other places (I know the topic has been brought up several times on the forum, only have this one link).
The
.mdfile was mostly generated using pandoc (only alterating the head of the file).Changes have also been made to the
.rsttemplate as well as DEP-1 in order to point to the markdown template, while the markdown template also points to the restructured text one