[llvm] r337509 - [docs] Add support for Markdown documentation in Sphinx

[Michael Spencer via llvm-commits]

On Thu, Jul 19, 2018 at 5:12 PM Michael Spencer <bigcheesegs at gmail.com>
wrote:

> It seems the bots have a very old version of Sphinx.  The source_suffix
> option was extended to support lists in 1.3 (current version is 1.8).
> I've asked for an upgrade and will revert shortly (15m) if it takes longer
> to get that sorted out.
>
> - Michael Spencer
>

Reverted in r337513.

- Michael Spencer


>
>
> On Thu, Jul 19, 2018 at 4:46 PM Michael J. Spencer via llvm-commits <
> llvm-commits at lists.llvm.org> wrote:
>
>> Author: mspencer
>> Date: Thu Jul 19 16:40:58 2018
>> New Revision: 337509
>>
>> URL: http://llvm.org/viewvc/llvm-project?rev=337509&view=rev
>> Log:
>> [docs] Add support for Markdown documentation in Sphinx
>>
>> Differential Revision: https://reviews.llvm.org/D44910
>>
>> Added:
>>     llvm/trunk/docs/MarkdownQuickstartTemplate.md
>> Modified:
>>     llvm/trunk/docs/conf.py
>>     llvm/trunk/docs/index.rst
>>
>> Added: llvm/trunk/docs/MarkdownQuickstartTemplate.md
>> URL:
>> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/MarkdownQuickstartTemplate.md?rev=337509&view=auto
>>
>> ==============================================================================
>> --- llvm/trunk/docs/MarkdownQuickstartTemplate.md (added)
>> +++ llvm/trunk/docs/MarkdownQuickstartTemplate.md Thu Jul 19 16:40:58 2018
>> @@ -0,0 +1,157 @@
>> +# Markdown Quickstart Template
>> +
>> +## Introduction and Quickstart
>> +
>> +This document is meant to get you writing documentation as fast as
>> possible
>> +even if you have no previous experience with Markdown. The goal is to
>> take
>> +someone in the state of "I want to write documentation and get it added
>> to
>> +LLVM's docs" and turn that into useful documentation mailed to
>> llvm-commits
>> +with as little nonsense as possible.
>> +
>> +You can find this document in `docs/MarkdownQuickstartTemplate.md`. You
>> +should copy it, open the new file in your text editor, write your docs,
>> and
>> +then send the new document to llvm-commits for review.
>> +
>> +Focus on *content*. It is easy to fix the Markdown syntax
>> +later if necessary, although Markdown tries to imitate common
>> +plain-text conventions so it should be quite natural. A basic knowledge
>> of
>> +Markdown syntax is useful when writing the document, so the last
>> +~half of this document (starting with [Example
>> Section](#example-section)) gives examples
>> +which should cover 99% of use cases.
>> +
>> +Let me say that again: focus on *content*. But if you really need to
>> verify
>> +Sphinx's output, see `docs/README.txt` for information.
>> +
>> +Once you have finished with the content, please send the `.md` file to
>> +llvm-commits for review.
>> +
>> +## Guidelines
>> +
>> +Try to answer the following questions in your first section:
>> +
>> +1. Why would I want to read this document?
>> +
>> +2. What should I know to be able to follow along with this document?
>> +
>> +3. What will I have learned by the end of this document?
>> +
>> +Common names for the first section are `Introduction`, `Overview`, or
>> +`Background`.
>> +
>> +If possible, make your document a "how to". Give it a name `HowTo*.md`
>> +like the other "how to" documents. This format is usually the easiest
>> +for another person to understand and also the most useful.
>> +
>> +You generally should not be writing documentation other than a "how to"
>> +unless there is already a "how to" about your topic. The reason for this
>> +is that without a "how to" document to read first, it is difficult for a
>> +person to understand a more advanced document.
>> +
>> +Focus on content (yes, I had to say it again).
>> +
>> +The rest of this document shows example Markdown markup constructs
>> +that are meant to be read by you in your text editor after you have
>> copied
>> +this file into a new file for the documentation you are about to write.
>> +
>> +## Example Section
>> +
>> +Your text can be *emphasized*, **bold**, or `monospace`.
>> +
>> +Use blank lines to separate paragraphs.
>> +
>> +Headings (like `Example Section` just above) give your document its
>> +structure.
>> +
>> +### Example Subsection
>> +
>> +Make a link [like this](http://llvm.org/). There is also a more
>> +sophisticated syntax which [can be more readable] for longer links since
>> +it disrupts the flow less. You can put the `[link name]: <URL>` block
>> +pretty much anywhere later in the document.
>> +
>> +[can be more readable]: http://en.wikipedia.org/wiki/LLVM
>> +
>> +Lists can be made like this:
>> +
>> +1. A list starting with `[0-9].` will be automatically numbered.
>> +
>> +1. This is a second list element.
>> +
>> +   1. Use indentation to create nested lists.
>> +
>> +You can also use unordered lists.
>> +
>> +* Stuff.
>> +
>> +  + Deeper stuff.
>> +
>> +* More stuff.
>> +
>> +#### Example Subsubsection
>> +
>> +You can make blocks of code like this:
>> +
>> +```
>> +int main() {
>> +  return 0;
>> +}
>> +```
>> +
>> +As an extension to markdown, you can also specify a highlighter to use.
>> +
>> +``` C++
>> +int main() {
>> +  return 0;
>> +}
>> +```
>> +
>> +For a shell session, use a `console` code block.
>> +
>> +```console
>> +$ echo "Goodbye cruel world!"
>> +$ rm -rf /
>> +```
>> +
>> +If you need to show LLVM IR use the `llvm` code block.
>> +
>> +``` llvm
>> +define i32 @test1() {
>> +entry:
>> +  ret i32 0
>> +}
>> +```
>> +
>> +Some other common code blocks you might need are `c`, `objc`, `make`,
>> +and `cmake`. If you need something beyond that, you can look at the [full
>> +list] of supported code blocks.
>> +
>> +[full list]: http://pygments.org/docs/lexers/
>> +
>> +However, don't waste time fiddling with syntax highlighting when you
>> could
>> +be adding meaningful content. When in doubt, show preformatted text
>> +without any syntax highlighting like this:
>> +
>> +                          .
>> +                           +:.
>> +                       ..:: ::
>> +                    .++:+:: ::+:.:.
>> +                   .:+           :
>> +            ::.::..::            .+.
>> +          ..:+    ::              :
>> +    ......+:.                    ..
>> +          :++.    ..              :
>> +            .+:::+::              :
>> +            ..   . .+            ::
>> +                     +.:      .::+.
>> +                      ...+. .: .
>> +                         .++:..
>> +                          ...
>> +
>> +##### Hopefully you won't need to be this deep
>> +
>> +If you need to do fancier things than what has been shown in this
>> document,
>> +you can mail the list or check the [Common Mark spec].  Sphinx specific
>> +integration documentation can be found in the [recommonmark docs].
>> +
>> +[Common Mark spec]: http://spec.commonmark.org/0.28/
>> +[recommonmark docs]:
>> http://recommonmark.readthedocs.io/en/latest/index.html
>>
>> Modified: llvm/trunk/docs/conf.py
>> URL:
>> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/conf.py?rev=337509&r1=337508&r2=337509&view=diff
>>
>> ==============================================================================
>> --- llvm/trunk/docs/conf.py (original)
>> +++ llvm/trunk/docs/conf.py Thu Jul 19 16:40:58 2018
>> @@ -31,7 +31,9 @@ extensions = ['sphinx.ext.intersphinx',
>>  templates_path = ['_templates']
>>
>>  # The suffix of source filenames.
>> -source_suffix = '.rst'
>> +source_suffix = ['.rst', '.md']
>> +
>> +source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
>>
>>  # The encoding of source files.
>>  #source_encoding = 'utf-8-sig'
>>
>> Modified: llvm/trunk/docs/index.rst
>> URL:
>> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=337509&r1=337508&r2=337509&view=diff
>>
>> ==============================================================================
>> --- llvm/trunk/docs/index.rst (original)
>> +++ llvm/trunk/docs/index.rst Thu Jul 19 16:40:58 2018
>> @@ -79,6 +79,7 @@ representation.
>>     yaml2obj
>>     HowToSubmitABug
>>     SphinxQuickstartTemplate
>> +   MarkdownQuickstartTemplate
>>     Phabricator
>>     TestingGuide
>>     tutorial/index
>> @@ -292,6 +293,7 @@ For API clients and LLVM developers.
>>     XRayFDRFormat
>>     PDB/index
>>     CFIVerify
>> +   SpeculativeLoadHardening
>>
>>  :doc:`WritingAnLLVMPass`
>>     Information on how to write LLVM transformations and analyses.
>> @@ -425,6 +427,9 @@ For API clients and LLVM developers.
>>  :doc:`CFIVerify`
>>    A description of the verification tool for Control Flow Integrity.
>>
>> +:doc:`SpeculativeLoadHardening`
>> +  A description of the Speculative Load Hardening mitigation for Spectre
>> v1.
>> +
>>  Development Process Documentation
>>  =================================
>>
>>
>>
>> _______________________________________________
>> 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/20180719/7b57dcd0/attachment.html>