[PATCH] D44910: [docs] Add Markdown support to Sphinx

[Chandler Carruth via llvm-commits]

On Mon, Mar 26, 2018 at 3:30 PM Michael Spencer via llvm-commits <
llvm-commits at lists.llvm.org> wrote:

> On Mon, Mar 26, 2018 at 3:10 PM, Chandler Carruth via Phabricator <
> reviews at reviews.llvm.org> wrote:
>
>> chandlerc added a comment.
>>
>> FWIW, I'm really, really happy to have this. =D
>>
>> But we should hear from others whether they're happy with this direction.
>
>
> Should this (or just an RFC) go to llvm-dev to get more input?
>

Yeah, I think an RFC to establish direction and answer questions like the
below one makes sense. Can be really short and focused.


>
>
>> Also, should we update any of our documentation recommending one format
>> or the other? I feel like markdown has "won" in the same sense that GitHub
>> has "won" -- it's the place with the growing ecosystem, even when its
>> functionality is actually inferior to reStructuredText. My inclination is
>> always to go with ecosystem, but others may have different opinions here.
>>
>>
> There are some major things that markdown is missing like cross document
> references and toctree, however recommonmark has some direct support for
> those (although this patch doesn't enable all of them) and supports
> escaping to reStructuredText.
>

Nice! This seems to be an effective way to blend the advantages of each
system.


>   I'm fine with writing new docs in markdown + extensions-when-needed, but
> I'm a bit concerned with rewriting the existing documentation (including
> LangRef) in markdown due to the work it will take.
>

Strongly agreed. I see little or no value in rewriting things. I mostly see
value in leveraging the markdown infrastructure when and where we can going
forward.


>
>
>>
>>
>> ================
>> Comment at: docs/MarkdownQuickstartTemplate.md:102
>> +
>> +``` C++
>> +int main() {
>> ----------------
>> capital or lowercase `c` here?
>>
>>
> Looks like it's case insensitive.  It's documented as lowercase:
> http://pygments.org/docs/lexers/ .
>
>
>>
>> https://reviews.llvm.org/D44910
>>
>>
>>
>>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20180327/3fd31fbe/attachment.html>