From caefe42c66ae8e67c8bd6ac2502e85f13cae38bf Mon Sep 17 00:00:00 2001 From: "Michael J. Spencer" Date: Fri, 20 Jul 2018 00:24:36 +0000 Subject: [PATCH] Revert "[docs] Add support for Markdown documentation in Sphinx" The buildbots have an old version of Sphinx (need at least 1.3). Revert until they are upgraded. llvm-svn: 337513 --- llvm/docs/MarkdownQuickstartTemplate.md | 157 -------------------------------- llvm/docs/conf.py | 4 +- llvm/docs/index.rst | 5 - 3 files changed, 1 insertion(+), 165 deletions(-) delete mode 100644 llvm/docs/MarkdownQuickstartTemplate.md diff --git a/llvm/docs/MarkdownQuickstartTemplate.md b/llvm/docs/MarkdownQuickstartTemplate.md deleted file mode 100644 index 7341521..0000000 --- a/llvm/docs/MarkdownQuickstartTemplate.md +++ /dev/null @@ -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]: ` 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 diff --git a/llvm/docs/conf.py b/llvm/docs/conf.py index 0fccb50..ce7df14 100644 --- a/llvm/docs/conf.py +++ b/llvm/docs/conf.py @@ -31,9 +31,7 @@ extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo'] 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' diff --git a/llvm/docs/index.rst b/llvm/docs/index.rst index 6a66454..2173f94 100644 --- a/llvm/docs/index.rst +++ b/llvm/docs/index.rst @@ -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 ================================= -- 2.7.4