and
also review [how flang uses modern C++ features](docs/C++17.md).
+If you are interested in writing new documentation, follow
+[markdown style guide from LLVM](https://github.com/llvm/llvm-project/blob/master/llvm/docs/MarkdownQuickstartTemplate.md).
+
## Supported C++ compilers
Flang is written in C++17.
<build-dir>/tools/flang/docs/doxygen/html # for flang docs
```
+## Generate Sphinx-based Documentation
+<!TODO: Add webpage once we have a website.
+!>
+Flang documentation should preferably be written in `markdown(.md)` syntax (they can be in `reStructuredText(.rst)` format as well but markdown is recommended in first place), it
+is mostly meant to be processed by the Sphinx documentation generation
+system to create HTML pages which would be hosted on the webpage of flang and
+updated periodically.
+
+If you would like to generate and view the HTML locally, install
+Sphinx <http://sphinx-doc.org/> and then:
+
+- Pass `-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF` to the cmake command.
+
+```
+cd ~/llvm-project/build
+cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
+make docs-flang-html
+
+It will generate html in
+
+ $BROWSER <build-dir>/tools/flang/docs/html/
+```
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
-
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']
templates_path = ['_templates']
# The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = {
+ '.rst': 'restructuredtext',
+}
+try:
+ import recommonmark
+except ImportError:
+ # manpages do not use any .md sources
+ if not tags.has('builder-man'):
+ raise
+else:
+ import sphinx
+ if sphinx.version_info >= (3, 0):
+ # This requires 0.5 or later.
+ extensions.append('recommonmark')
+ else:
+ source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+ source_suffix['.md'] = 'markdown'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
-master_doc = 'ReleaseNotes'
+master_doc = 'Overview'
# General information about the project.
project = u'Flang'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
- ('ReleaseNotes', 'Flang.tex', u'Flang Documentation',
+ ('Overview', 'Flang.tex', u'Flang Documentation',
u'The Flang Team', 'manual'),
]
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('ReleaseNotes', 'Flang', u'Flang Documentation',
- u'The Flang Team', 'Flang', 'One line description of project.',
+ ('Overview', 'Flang', u'Flang Documentation',
+ u'The Flang Team', 'Flang', 'A Fortran front end for LLVM.',
'Miscellaneous'),
]