Skip to content
Snippets Groups Projects
Unverified Commit 0122a746 authored by Imran Iqbal's avatar Imran Iqbal
Browse files

docs: remove files which aren't formula-specific [skip ci] 

Further reason is to avoid issues with `rst-lint`:

```
ERROR docs/CONTRIBUTING_DOCS.rst:29 Unknown interpreted text role "ref".
WARNING docs/CONTRIBUTING_DOCS.rst:40 malformed hyperlink target.
ERROR docs/index.rst:10 Unknown directive type "toctree".
```
parent d46cd1d4
Branches
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
docs/CONTRIBUTING_DOCS.rst deleted 100644 → 0
+ 0
− 95
View file @ d46cd1d4
.. _contributing_docs:
Contributing documentation
==========================
|docs|
.. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest
:alt: Documentation Status
:scale: 100%
:target: https://rabbitmq-formula.readthedocs.io/en/latest/?badge=latest
Toolchain
^^^^^^^^^
The documentation for this formula is written in
`reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_
(also known as RST, ReST, or reST).
It is built by
`Sphinx <https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
and hosted on
`Read the Docs <https://en.wikipedia.org/wiki/Read_the_Docs>`_.
Adding a new page
^^^^^^^^^^^^^^^^^
Adding a new page involves two steps:
#. Use the
:ref:`provided page template <saltstack_formulas_rst_page_template>`
to create a new page.
#. Add the page name under the ``toctree`` list in ``index.rst``.
a. Do not just append it to the list.
#. Select the best place where it fits within the overall documentation.
.. _saltstack_formulas_rst_page_template:
SaltStack-Formulas' RST page template
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use the following template when creating a new page.
This ensures consistency across the documentation for this formula.
The heading symbols have been selected in accordance to the output rendered by the
`Markdown to reStructuredText converter <https://github.com/miyakogi/m2r#restrictions>`_
we are using for some of the pages of this documentation.
.. code-block:: rst
.. _template:
[Page title]
============
[Introductory paragraph]
.. contents:: **Table of Contents**
[Heading 2]
-----------
[Heading 3]
^^^^^^^^^^^
[Heading 4]
~~~~~~~~~~~
[Heading 5]
"""""""""""
[Heading 6]
###########
#. The first line is an anchor that can be used to link back to (the top of)
this file.
a. Change this to be the lowercase version of the file name.
#. Do not include the ``.rst`` file extension.
#. Use hyphens (``-``) instead of spaces or non-letter characters.
#. Change the ``[Page title]`` accordingly, matching the same number of equals
signs (``=``) underneath.
#. Change the ``[Introductory paragraph]`` to be a short summary of the page
content.
Use no more than three paragraphs for this.
#. Leave the ``..contents:: **Table of Contents**`` line as it is.
#. Use the remaining headings as required to break up the page content.
a. You will rarely need to use beyond ``[Heading 4]``.
#. Again, no single heading should have more than about three paragraphs of
content before the next heading or sub-heading is used.
Obviously, it is not necessary to follow the steps in the order above.
For example, it is usually easier to write the ``[Introductory paragraph]``
at the end.
docs/conf.py deleted 100644 → 0
+ 0
− 173
View file @ d46cd1d4
# -*- coding: utf-8 -*-
"""Configuration file for the Sphinx documentation builder.
This file does only contain a selection of the most common options. For a
full list see the documentation:
* http://www.sphinx-doc.org/en/stable/config
"""
from __future__ import division, print_function, unicode_literals
# from datetime import datetime
from recommonmark.parser import CommonMarkParser
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
__author__ = 'Imran Iqbal' # noqa: E221
__copyright__ = 'Copyright (C) 2019, MYII' # noqa: E221
__license__ = 'Apache-2.0' # noqa: E221
__version__ = 'latest' # noqa: E221
__maintainer__ = 'Imran Iqbal' # noqa: E221
# -- Project information -----------------------------------------------------
project = 'rabbitmq-formula'
copyright = __copyright__.replace('Copyright (C) ', '') # noqa: A001
author = __author__
version = __version__
release = __version__
# -- General configuration ---------------------------------------------------
# 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 = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['templates', '_templates', '.templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst', '.md']
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for the reStructuredText parser ---------------------------------
file_insertion_enabled = False
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'rabbitmq-formula'
# -- Options for Markdown output ---------------------------------------------
source_parsers = {
'.md': CommonMarkParser,
}
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(
'index',
'rabbitmq-formula.tex',
u'rabbitmq-formula Documentation',
u'',
'manual',
),
]
# -- Functions: `setup`, docstring preprocessing, etc. -----------------------
def setup(app):
"""Prepare the Sphinx application object.
Used for providing a custom CSS file for override styles.
Parameters
----------
app : object
The Sphinx application object.
Returns
-------
app : object
The Sphinx application object.
"""
app.add_stylesheet('css/custom.css')
return app
docs/index.rst deleted 100644 → 0
+ 0
− 20
View file @ d46cd1d4
.. _index:
.. ``rabbitmq-formula`` documentation master file.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to rabbitmq-formula's documentation!
============================================
.. toctree::
:maxdepth: 2
:caption: Contents
:numbered:
:glob:
README <README>
CONTRIBUTING
TOFS_pattern
AUTHORS
CHANGELOG
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment