llvm dev - Mar 2018 - [RFC] Markdown for documentation

There's been some desire recently to start writing documentation in
Markdown instead of reStructuredText. I put up a [patch](
https://reviews.llvm.org/D44910) for that, but we should figure out a
policy on how we want our documentation written first.

The desire to use Markdown comes mostly from it being simpler, and having
much wider adoption.  It does lack some of the feature that reStructuredText
has; however, the recommonmark plugin for Sphinx adds extensions for most
of them and has an escape to RST when all else fails.

My suggestion is that we don't touch the existing documentation, but
encourage new documentation to be written in Markdown+Sphinx extensions.

- Michael Spencer
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20180329/ec2cb33f/attachment.html>

If Sphinx consumes Markdown, great, let's do it.

We can migrate docs from .rst to .md easily over time.

On Thu, Mar 29, 2018 at 1:26 PM Michael Spencer via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> There's been some desire recently to start writing documentation in
> Markdown instead of reStructuredText. I put up a [patch](
> https://reviews.llvm.org/D44910) for that, but we should figure out a
> policy on how we want our documentation written first.
>
> The desire to use Markdown comes mostly from it being simpler, and having
> much wider adoption.  It does lack some of the feature that
reStructuredText
> has; however, the recommonmark plugin for Sphinx adds extensions for most
> of them and has an escape to RST when all else fails.
>
> My suggestion is that we don't touch the existing documentation, but
> encourage new documentation to be written in Markdown+Sphinx extensions.
>
> - Michael Spencer
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20180329/f9f2ccb6/attachment.html>

Agreed.  Markdown is also nice for the github integration.  It might 
make some of our docs more easily discoverable.  (and maybe editable 
someday)


On 03/29/2018 01:34 PM, Reid Kleckner via llvm-dev
wrote:
> If Sphinx consumes Markdown, great, let's do it.
>
> We can migrate docs from .rst to .md easily over time.
>
> On Thu, Mar 29, 2018 at 1:26 PM Michael Spencer via llvm-dev 
> <llvm-dev at lists.llvm.org <mailto:llvm-dev at
lists.llvm.org>> wrote:
>
>     There's been some desire recently to start writing documentation
>     in Markdown instead of reStructuredText. I put up a
>     [patch](https://reviews.llvm.org/D44910) for that, but we should
>     figure out a policy on how we want our documentation written first.
>
>     The desire to use Markdown comes mostly from it being simpler, and
>     having much wider adoption.  It does lack some of the feature that
>     reStructuredText has; however, the recommonmark plugin for Sphinx
>     adds extensions for most of them and has an escape to RST when all
>     else fails.
>
>     My suggestion is that we don't touch the existing documentation,
>     but encourage new documentation to be written in Markdown+Sphinx
>     extensions.
>
>     - Michael Spencer
>     _______________________________________________
>     LLVM Developers mailing list
>     llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>
>     http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
>
>
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20180329/853352bd/attachment.html>

I’d love Markdown documentation. It’s easy to read when rendered, easy to read +
navigate from a bare-bones text editor, pleasant to write, and has wide
adoption. I’m a fan.

(If there are any serious missing features, we could probably look into
something like Markdeep in the future, which is compatible with Markdown syntax
but adds some extra functionality for documentation, writing books, etc.)

- Jessica
> On Mar 29, 2018, at 1:25 PM, Michael Spencer via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
> There's been some desire recently to start writing documentation in
Markdown instead of reStructuredText. I put up a
[patch](https://reviews.llvm.org/D44910 <https://reviews.llvm.org/D44910>)
for that, but we should figure out a policy on how we want our documentation
written first.
> 
> The desire to use Markdown comes mostly from it being simpler, and having
much wider adoption.  It does lack some of the feature that reStructuredText
has; however, the recommonmark plugin for Sphinx adds extensions for most of
them and has an escape to RST when all else fails.
> 
> My suggestion is that we don't touch the existing documentation, but
encourage new documentation to be written in Markdown+Sphinx extensions.
> 
> - Michael Spencer
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20180402/061eec03/attachment.html>

I don't like the fact that there are so many different Markdown versions
especially when compared to RST, but it does seem that Markdown has become the
more popular format. If our tooling supports it and we document what dialect we
use (and perhaps even have some form of ninja check-docs to enforce it) I think
that this makes sense.

-- adrian
> On Mar 29, 2018, at 1:25 PM, Michael Spencer via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
> There's been some desire recently to start writing documentation in
Markdown instead of reStructuredText. I put up a
[patch](https://reviews.llvm.org/D44910 <https://reviews.llvm.org/D44910>)
for that, but we should figure out a policy on how we want our documentation
written first.
> 
> The desire to use Markdown comes mostly from it being simpler, and having
much wider adoption.  It does lack some of the feature that reStructuredText
has; however, the recommonmark plugin for Sphinx adds extensions for most of
them and has an escape to RST when all else fails.
> 
> My suggestion is that we don't touch the existing documentation, but
encourage new documentation to be written in Markdown+Sphinx extensions.
> 
> - Michael Spencer
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20180402/2bb31d66/attachment.html>