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 :) |
Co-authored-by: Gert Van Gool <[email protected]>
| @@ -295,21 +295,25 @@ DEP format | |||
|
|
|||
| To save everyone time reading DEPs, they need to follow a common format | |||
| and outline; this section describes that format. In most cases, it's probably | |||
| easiest to start with copying the provided `DEP template <../template.rst>`_, | |||
| easiest to start with copying one of the provided DEP templates | |||
| (`rst template <../template.rst>` - `md template <../template.md>`)_, | |||
There was a problem hiding this comment.
This doesn't render correctly. Looking at the old link, I think it should be:
| (`rst template <../template.rst>` - `md template <../template.md>`)_, | |
| (`rst template <../template.rst>`_ - `md template <../template.md>`_), |
| or `Markdown frontmatter <https://github.com/Kernix13/markdown-cheatsheet/blob/master/frontmatter.md>`_ | ||
| depending on which template you are using. |
There was a problem hiding this comment.
I think it's clear enough that which you use would depend on the template chosen:
| or `Markdown frontmatter <https://github.com/Kernix13/markdown-cheatsheet/blob/master/frontmatter.md>`_ | |
| depending on which template you are using. | |
| or `Markdown frontmatter <https://github.com/Kernix13/markdown-cheatsheet/blob/master/frontmatter.md>`_. |
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