[llvm] r337731 - Revert "[docs] Add support for Markdown documentation in Sphinx"
Chandler Carruth via llvm-commits
llvm-commits at lists.llvm.org
Sun Aug 5 23:06:30 PDT 2018
Which bot are you looking at? I've still not managed to get LLVM's green,
but for unrelated causes....
http://lab.llvm.org:8011/builders/llvm-sphinx-docs
I'm still poking at it between doing other things.
On Sun, Aug 5, 2018 at 11:01 PM Dmitri Gribenko via llvm-commits <
llvm-commits at lists.llvm.org> wrote:
> Thanks! Five hours later, the bot is still green.
> On Sun, Aug 5, 2018 at 5:39 PM Chandler Carruth <chandlerc at gmail.com>
> wrote:
> >
> > I've re-landed the patch in r338977 and will watch the bot to see how it
> goes.
> >
> > On Sun, Aug 5, 2018 at 3:31 PM Dmitri Gribenko <gribozavr at gmail.com>
> wrote:
> >>
> >> Hi,
> >>
> >> Sorry for the delayed response -- llvm-commits goes into "archived"
> >> for me. Please email me directly (on a separate thread) in future so
> >> that it pops up in my inbox.
> >>
> >> I have installed python-recommonmark, python3-recommonmark, and
> >> recommonmark-scripts on the bot. Please let me know if it works and
> >> if it is sufficient.
> >>
> >> Dmitri
> >>
> >> On Tue, Jul 24, 2018 at 7:49 PM Mike Edwards <mike at sqlby.me> wrote:
> >> >
> >> > Hi Dimitri,
> >> > Would it be possible to get some assistance here? We would like to
> get the recommonmark python package added to the llvm-sphinx-docs bot which
> is currently running on gribozavr3. It also looks like the version of
> sphinx could be updated too. Since you are the listed owner for this node
> we are hoping you could help out with this request.
> >> >
> >> > Thanks,
> >> > Mike
> >> >
> >> > On Tue, Jul 24, 2018 at 7:39 PM, Mike Edwards <mike at sqlby.me> 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
> >> >>
> >> >>
> >> >
> >>
> >>
> >> --
> >> main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
> >> (j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/
>
>
>
> --
> main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
> (j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/
> _______________________________________________
> 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/20180805/5f15dfd1/attachment.html>
More information about the llvm-commits
mailing list