-
Notifications
You must be signed in to change notification settings - Fork 83
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
provide a .md template alongside the .rst one #94
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it’d be worth updating the point about preambles below. Perhaps just removing the specifics:
A preamble -- metadata about the DEP […]
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
updated
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Makes sense to me! Looking good
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 :) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
About the Markdown
vs MarkDown
, I updated it to be consistent (I think the lowercase d is the correct casing).
Also suggested some syntax fixes for the rST links.
(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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
`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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
`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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
.md
file was mostly generated using pandoc (only alterating the head of the file).Changes have also been made to the
.rst
template as well as DEP-1 in order to point to the markdown template, while the markdown template also points to the restructured text one