[llvm] r337731 - Revert "[docs] Add support for Markdown documentation in Sphinx"
Chandler Carruth via llvm-commits
llvm-commits at lists.llvm.org
Mon Aug 6 03:55:07 PDT 2018
Finally got the bot to pass.
+Mike Edwards <mike at sqlby.me> - I don't see an update in llvm.org/docs yet
-- is that just delayed and synced with a cronjob or something?
On Sun, Aug 5, 2018 at 11:06 PM Chandler Carruth <chandlerc at gmail.com>
wrote:
> 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/20180806/03300972/attachment.html>
More information about the llvm-commits
mailing list