[llvm] r337731 - Revert "[docs] Add support for Markdown documentation in Sphinx"

Tue Jul 24 19:39:20 PDT 2018

Sorry, I thought all of the docs generation happened on the lists.llvm.org
server so I updated the python packages there.  I didn't realize there was
a seperate bot for this.  I need to figure out which node this bot is on
and if I have access to it I can fix it.  If not I'll ping the list to find
the owner and get it sorted out.

No need to apologize, I want to get it working too. :)

On Tue, Jul 24, 2018 at 11:51 AM, Chandler Carruth <chandlerc at gmail.com>
wrote:

> Hey Mike,
>
> I know you and Michael had a separate thread going, but just wondering if
> there is anything else someone could do to help out getting this sorted?
>
> (Sorry, I know, I'm a bit anxious...)
>
>
> On Mon, Jul 23, 2018 at 1:00 PM Michael J. Spencer via llvm-commits <
> llvm-commits at lists.llvm.org> wrote:
>
>> Author: mspencer
>> Date: Mon Jul 23 13:00:32 2018
>> New Revision: 337731
>>
>> URL: http://llvm.org/viewvc/llvm-project?rev=337731&view=rev
>> Log:
>> Revert "[docs] Add support for Markdown documentation in Sphinx"
>>
>> Looks like this bot hasn't been updated yet.
>>
>> Removed:
>>     llvm/trunk/docs/MarkdownQuickstartTemplate.md
>> Modified:
>>     llvm/trunk/docs/conf.py
>>     llvm/trunk/docs/index.rst
>>
>> Removed: llvm/trunk/docs/MarkdownQuickstartTemplate.md
>> URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/
>> MarkdownQuickstartTemplate.md?rev=337730&view=auto
>> ============================================================
>> ==================
>> --- llvm/trunk/docs/MarkdownQuickstartTemplate.md (original)
>> +++ llvm/trunk/docs/MarkdownQuickstartTemplate.md (removed)
>> @@ -1,157 +0,0 @@
>> -# 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=337731&r1=337730&r2=337731&view=diff
>> ============================================================
>> ==================
>> --- llvm/trunk/docs/conf.py (original)
>> +++ llvm/trunk/docs/conf.py Mon Jul 23 13:00:32 2018
>> @@ -31,9 +31,7 @@ extensions = ['sphinx.ext.intersphinx',
>>  templates_path = ['_templates']
>>
>>  # The suffix of source filenames.
>> -source_suffix = ['.rst', '.md']
>> -
>> -source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
>> +source_suffix = '.rst'
>>
>>  # 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=337731&r1=337730&r2=337731&view=diff
>> ============================================================
>> ==================
>> --- llvm/trunk/docs/index.rst (original)
>> +++ llvm/trunk/docs/index.rst Mon Jul 23 13:00:32 2018
>> @@ -79,7 +79,6 @@ representation.
>>     yaml2obj
>>     HowToSubmitABug
>>     SphinxQuickstartTemplate
>> -   MarkdownQuickstartTemplate
>>     Phabricator
>>     TestingGuide
>>     tutorial/index
>> @@ -293,7 +292,6 @@ For API clients and LLVM developers.
>>     XRayFDRFormat
>>     PDB/index
>>     CFIVerify
>> -   SpeculativeLoadHardening
>>
>>  :doc:`WritingAnLLVMPass`
>>     Information on how to write LLVM transformations and analyses.
>> @@ -427,9 +425,6 @@ 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/20180724/bbccc088/attachment.html>