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

Tue Jul 24 19:46:55 PDT 2018

Cool, feel free to grab me on IRC if I can help connect dots.

On Tue, Jul 24, 2018 at 7:39 PM Mike Edwards via llvm-commits <
llvm-commits at lists.llvm.org> wrote:

> 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
>>>
>>
> _______________________________________________
> 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/bbf0f071/attachment.html>