Merge 72167a9 into 4cf007c

CONTRIBUTORS.md → CONTRIBUTORS.rst

@@ -1,5 +1,5 @@
 Contributors
-===
+------------
 
 * Abdullah Hilson ([@abumalick](https://github.com/abumalick))
 * Amir Rachum ([@Nurdok](https://github.com/Nurdok))

docs/_templates/globaltoc.html

@@ -0,0 +1,21 @@
+<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
+
+<ul>
+  <li><a href="{{ pathto('index') }}">1. Home</a></li>
+  <li><a href="{{ pathto('usage') }}">2. Command Line Usage</a></li>
+  <li><a href="{{ pathto('profiles') }}">3. Profiles / Configuration</a></li>
+  <li><a href="{{ pathto('suppression') }}">4. Error Suppression</a></li>
+  <li><a href="{{ pathto('supported_tools') }}">5. Supported tools</a></li>
+  <li><a href="{{ pathto('contrib') }}">6. Contributing</a></li>
+  <li><a href="{{ pathto('changelog') }}">Changelog</a></li>
+  <li><a href="{{ pathto('contents') }}">Contents</a></li>
+</ul>
+
+{%- if display_toc %}
+  <hr>
+  {{ toc }}
+{%- endif %}
+
+<hr>
+<a href="{{ pathto('genindex') }}">Index</a>
+<hr>

docs/_templates/layout.html

@@ -0,0 +1,52 @@
+{#
+
+    Copied from:
+
+     https://raw.githubusercontent.com/pallets/pallets-sphinx-themes/b0c6c41849b4e15cbf62cc1d95c05ef2b3e155c8/src/pallets_sphinx_themes/themes/pocoo/layout.html
+
+    And removed the warning version (see #7331).
+
+#}
+
+{% extends "basic/layout.html" %}
+
+{% set metatags %}
+  {{- metatags }}
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+{%- endset %}
+
+{% block extrahead %}
+  {%- if page_canonical_url %}
+    <link rel="canonical" href="{{ page_canonical_url }}">
+  {%- endif %}
+  <script>DOCUMENTATION_OPTIONS.URL_ROOT = '{{ url_root }}';</script>
+  {{ super() }}
+{%- endblock %}
+
+{% block sidebarlogo %}
+  {% if pagename != "index" or theme_index_sidebar_logo %}
+    {{ super() }}
+  {% endif %}
+{% endblock %}
+
+{% block relbar2 %}{% endblock %}
+
+{% block sidebar2 %}
+  <span id="sidebar-top"></span>
+  {{- super() }}
+{%- endblock %}
+
+{% block footer %}
+  {{ super() }}
+  {%- if READTHEDOCS and not readthedocs_docsearch %}
+    <script>
+      if (typeof READTHEDOCS_DATA !== 'undefined') {
+        if (!READTHEDOCS_DATA.features) {
+          READTHEDOCS_DATA.features = {};
+        }
+        READTHEDOCS_DATA.features.docsearch_disabled = true;
+      }
+    </script>
+  {%- endif %}
+  {{ js_tag("_static/version_warning_offset.js") }}
+{% endblock %}

docs/_templates/links.html

@@ -0,0 +1,7 @@
+<h3>Useful Links</h3>
+<ul>
+  <li><a href="https://pypi.org/project/prospector/">prospector @ PyPI</a></li>
+  <li><a href="https://github.com/PyCQA/prospector/">prospector @ GitHub</a></li>
+  <li><a href="https://github.com/PyCQA/prospector/issues">Issue Tracker</a></li>
+  <li><a href="http://prospector.landscape.io/en/master/">Documentation</a>
+</ul>

docs/_templates/relations.html

@@ -0,0 +1,19 @@
+<h3>Related Topics</h3>
+<ul>
+  <li><a href="{{ pathto(master_doc) }}">Contents</a><ul>
+  {%- for parent in parents %}
+  <li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul>
+  {%- endfor %}
+    {%- if prev %}
+      <li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter')
+        }}">{{ prev.title }}</a></li>
+    {%- endif %}
+    {%- if next %}
+      <li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter')
+        }}">{{ next.title }}</a></li>
+    {%- endif %}
+  {%- for parent in parents %}
+  </ul></li>
+  {%- endfor %}
+  </ul></li>
+</ul>

docs/_templates/sidebarintro.html

@@ -0,0 +1,4 @@
+<h3>About prospector</h3>
+<p>
+  Prospector runs your favourite linters in a useful way
+</p>

docs/_templates/slim_searchbox.html

@@ -0,0 +1,15 @@
+{#
+    basic/searchbox.html with heading removed.
+#}
+{%- if pagename != "search" and builder != "singlehtml" %}
+<div id="searchbox" style="display: none" role="search">
+  <div class="searchformwrapper">
+    <form class="search" action="{{ pathto('search') }}" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel"
+        placeholder="Search"/>
+      <input type="submit" value="{{ _('Go') }}" />
+    </form>
+  </div>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+{%- endif %}

docs/changelog.rst

@@ -0,0 +1,5 @@
+.. _`changelog`:
+
+.. include:: ../CHANGELOG.rst
+
+

docs/conf.py

@@ -15,6 +15,10 @@
 import os
 import sys
 
+from prospector.__pkginfo__ import __version__ as version
+
+release = ".".join(version.split(".")[:2])
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -28,7 +32,11 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinxarg.ext"]
+extensions = [
+    "sphinxarg.ext",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -40,20 +48,19 @@
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = "index"
+master_doc = "contents"
 
 # General information about the project.
 project = u"Prospector"
-copyright = u"2014, Carl Crowder"
+copyright = u"2014-2020, Carl Crowder"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = "1.1.4"
-# The full version, including alpha/beta/rc tags.
-release = "1.1.4"
+# release = The short X.Y version.
+# version = The full version, including alpha/beta/rc tags.
+release = ".".join(version.split(".")[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -78,7 +85,7 @@
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-# add_module_names = True
+add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
@@ -98,7 +105,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "default"
+html_theme = "alabaster"
 
 # 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
@@ -110,10 +117,10 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-# html_title = None
+html_title = "prospector documentation"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-# html_short_title = None
+html_short_title = "prospector-%s" % version
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -127,7 +134,7 @@
 # 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"]
+# html_static_path = ["_static"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -143,17 +150,32 @@
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    "index": [
+        "slim_searchbox.html",
+        "sidebarintro.html",
+        "globaltoc.html",
+        "links.html",
+        "sourcelink.html",
+    ],
+    "**": [
+        "slim_searchbox.html",
+        "globaltoc.html",
+        "relations.html",
+        "links.html",
+        "sourcelink.html",
+    ],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 # html_additional_pages = {}
 
 # If false, no module index is generated.
-# html_domain_indices = True
+html_domain_indices = True
 
 # If false, no index is generated.
-# html_use_index = True
+html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
 # html_split_index = False

docs/contents.rst

@@ -0,0 +1,22 @@
+Contents
+---------
+
+.. toctree::
+   :caption: Table of Contents
+   :maxdepth: 2
+   :numbered: 1
+
+   index
+   usage
+   profiles
+   suppression
+   supported_tools
+   contrib
+
+
+.. only:: html
+
+   .. toctree::
+      :maxdepth: 1
+
+      changelog

docs/contrib.rst

@@ -1,5 +1,5 @@
-Development and Contributing
-============================
+Contributing
+============
 
 All contributions are very welcome! You can contribute in many ways:
 
@@ -37,8 +37,17 @@ handling the output of other tools. However, please do run them before submittin
 
     nosetests tests/
 
-Prospector targets Python 2.7, 3.4, 3.5, 3.6, 3.7 and 3.8. You can use `tox`_ to test this locally,
+Prospector targets Python 3.5, 3.6, 3.7 and 3.8. You can use `tox`_ to test this locally,
 and all tests are run on `travis-ci.org`_.
 
 .. _tox: https://tox.readthedocs.io/en/latest/
 .. _travis-ci.org: https://travis-ci.org/PyCQA/prospector
+
+.. include:: ../CONTRIBUTORS.rst
+
+Developper Reference
+--------------------
+.. toctree::
+   :maxdepth: 2
+
+   reference

docs/index.rst

@@ -24,7 +24,7 @@ About
 Prospector is a tool to analyse Python code and output information about errors, potential problems, convention violations and complexity.
 
 It brings together the functionality of other Python analysis tools such as `Pylint`_, `pep8`_, and `McCabe complexity`_.
-See the :doc:`Supported Tools<supported_tools>` section for a complete list.
+See the :doc:`Supported Tools<supported_tools>` section for a complete list of default and optional extra tools.
 
 The primary aim of Prospector is to be useful 'out of the box'. A common complaint of other
 Python analysis tools is that it takes a long time to filter through which errors are relevant
@@ -40,20 +40,38 @@ and adapts the output depending on the libraries your project uses.
 Installation
 ------------
 
-You can install using ``pip``::
+You can install default tools using ``pip`` command::
 
     pip install prospector
 
-To install optional dependencies such as ``pyroma``::
+
+For a full list of optional extra tools, and specific examples to install each of them,
+see the :doc:`page on supported tools <supported_tools>`.
+
+For example to install an optional tool such as ``pyroma``::
 
     pip install prospector[with_pyroma]
 
 
-Some shells (such as ``Zsh``, the default shell of macOS Catalina) require brackets to be escaped::
+.. Note:: Some shells (such as ``Zsh``, the default shell of macOS Catalina) require brackets to be escaped
+   ::
+
+       pip install prospector\[with_pyroma\]
+
+
+To install two or more optional extra tools at the same time, they must be comma separated (and without spaces).
+For example to install mypy and bandit::
+
+    pip install prospector[with_mypy,with_bandit]
+
+
+And to install all optional extra tools at the same time, install prospector using the ``with_everything`` option::
+
+    pip install prospector[with_everything]
+
+
 
-    pip install prospector\[with_pyroma\]
 
-For a full list of optional extras, see the :doc:`page on supported tools <supported_tools>`.
 
 For best results, you should install prospector to the same place as your project and its dependencies. That is,
 if you are using virtual environments, install pip into that virtual environment alongside your code. This
@@ -138,23 +156,3 @@ License
 
 Prospector is available under the GPLv2 License.
 
-
-Contents:
-
-.. toctree::
-   :maxdepth: 1
-
-   usage
-   profiles
-   suppression
-   supported_tools
-   contrib
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`