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

Tue Jul 24 11:51:37 PDT 2018

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/7f808a24/attachment-0001.html>