* Markdown is the most common format on GitHub and most contributors are
more familiar with it than RST.
* This leads to mistakes in the RST syntax and/or folks just using
Markdown syntax and assuming it works.
* The release notes have a high number of edits and a high number of
views, we should optimise for making the common path easy. That is,
adding a bullet point and a link.
* Though GitHub can render RST and Markdown, its support for Markdown is
more complete (and neither handle the Sphinx directives well).
* We already have some Markdown docs in the llvm docs.
To keep the original formatting we do need some Sphinx directives still,
and those are provided by MyST which is already enabled.
https://myst-parser.readthedocs.io/en/latest/
I did have to enable an extension so we can substitute in the release
version.
https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2
Needing to use MyST means there is some special knowledge needed if you
want to do advanced things, but at least the basics remain Markdown.
Even in RST form, you still had to look up Sphinx syntax.
I also make use of a nested directive
https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives
to implement the prerelease warning.
The note about sections referred to another note that got removed in
4c72deb613d9d8838785b431facb3eb480fb2f51. I presume accidentally, so I
have restored that.
I also removed the "Update on required toolchains to build LLVM" header
because the section is now empty.
The other difference is that the table of contents now has a heading
"Contents". This is the default and I could not find a way to remove
that name. Otherwise it's the same table as you'd get from the RST
document.
Avoid creating an uncacheable conf variable by using a string instead of
a function reference. Also has the effect of avoiding triggering the
"config.cache" sphinx warning.
Requires myst_parser 0.19.0 (specifically
https://github.com/executablebooks/MyST-Parser/pull/696) which is over a
year old by now. Do we mandate any minimum version for these
dependencies?
The man pages do not depend on the doc present in markdown files, so
they can be built without myst_parser.
Doing so might allow llvm distributions to have less development
dependencies.
As we do not have the ennvironment to test these configuration, this
capability is provided on a best-effort basis.
This restores a capability accidentally lost in #65664.
Should have no effect on the online documentation, but it makes offline
builds more self-contained. With relative links however we have to
abstain from using `:manpage:` outside of man page cross-references.
Reviewed By: mysterymath
Differential Revision: https://reviews.llvm.org/D132794
This updates all the non-runtime project release notes to use the
version number from CMake instead of the hard-coded version numbers
in conf.py.
It also hides warnings about pre-releases when the git suffix
is dropped from the LLVM version in CMake.
Reviewed By: MaskRay
Differential Revision: https://reviews.llvm.org/D112181
Do not enforce recommonmark dependency if sphinx is called to build
manpages. In order to do this, try to import recommonmark first
and do not configure it if it's not available. Additionally, declare
a custom tags for the selected builder via CMake, and ignore
recommonmark import failure when 'man' target is used.
This will permit us to avoid the problematic recommonmark dependency
for the majority of Gentoo users that do not need to locally build
the complete documentation but want to have tool manpages.
Differential Revision: https://reviews.llvm.org/D83161
The "new way" of enabling recommonmark is only supported in recommonmark
0.5 and later. Use the deprecated approach with versions of Sphinx that
still support it.
If I understand correctly there's no way to use older versions of
recommonmark (<0.5) with newer versions of Sphinx (>3.0) because the old
approach got removed.
Differential revision: https://reviews.llvm.org/D75284
Update the Sphinx configuration for the removal of source_parsers in
Sphinx 3.0. The variable has been deprecated since version 1.8.
> Version 1.8 deprecates and version 3.0 removes the source_parsers
> configuration variable that was used by older recommonmark versions.
https://www.sphinx-doc.org/en/master/usage/markdown.html
Differential revision: https://reviews.llvm.org/D75284
Adds a custom sidebar to LLVM docs. Sidebar includes links to How to submit a bug and FAQ topics, as well as a Show Source link and search box.
llvm-svn: 372432
rL358749 added a documentation page in the Markdown format. Currently,
such pages are ignored in the configuration script for manual pages.
This patch fixes that.
Differential Revision: https://reviews.llvm.org/D60964
llvm-svn: 359860
Make sure all print statements are compatible with Python 2 and Python3 using
the `from __future__ import print_function` statement.
Differential Revision: https://reviews.llvm.org/D56249
llvm-svn: 350307
Summary:
Add a CommandGuide for llvm-objdump summarizing its usage along with some
general context.
Reviewers: beanz
Reviewed By: beanz
Subscribers: Eugene.Zelenko, llvm-commits
Differential Revision: https://reviews.llvm.org/D50034
llvm-svn: 339250
Sphinx.
We think the bot is updated now, so trying this again. I'm landing it
(with permission) as Michael is at a con at the moment.
Actual patch largely by Michael Spencer.
Differential Revision: https://reviews.llvm.org/D44910
llvm-svn: 338977
The pygments syntax highlighting package used by sphinx fails to parse
newer LLVM constructs or valid (at least to me) gas constructs like
`.secrel32 _function_name + 0`.
Disable this particular warning so the build doesn't abort as fixing
pygments doesn't seem a workable option here.
Differential Revision: https://reviews.llvm.org/D29794
llvm-svn: 294672
