docs: completely revamp documentation

andreoliwa · Aug 17, 2019 · dd9d3d7 · dd9d3d7
1 parent 0151931
commit dd9d3d7
Show file tree

Hide file tree

Showing 25 changed files with 414 additions and 249 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -6,6 +6,7 @@ root = true
 [*]
 end_of_line = lf
 insert_final_newline = true
+indent_style = space
 
 # Matches multiple files with brace expansion notation
 # Set default charset

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -1,3 +1,5 @@
+.. include:: targets.rst
+
 ============
 Contributing
 ============
@@ -23,18 +25,17 @@ articles, and such.
 Development
 ===========
 
-To set up ``nitpick`` for local development:
+To set up Nitpick_ for local development:
 
-1. Fork `nitpick <https://github.com/andreoliwa/nitpick>`_
-   (look for the "Fork" button).
+1. Fork Nitpick_ (look for the "Fork" button).
 
 2. Clone your fork locally::
 
     cd ~/Code
     git clone git@github.com:your_name_here/nitpick.git
     cd nitpick
 
-3. `Install Poetry globally using the recommended way <https://github.com/sdispater/poetry#installation>`_.
+3. Install Poetry_ globally using the recommended way.
 
 4. Create your virtualenv with pyenv (or some other tool you prefer)::
 
@@ -67,8 +68,7 @@ To set up ``nitpick`` for local development:
 
 9. Submit a pull request through the GitHub website.
 
-10. If your pull request is accepted, all your commits will be squashed into one,
-    and the `Angular Convention will be used on the commit message <https://github.com/conventional-changelog/conventional-changelog/tree/0e05028f70bbd3109e1a4b16262a9450153060de/packages/conventional-changelog-angular#angular-convention>`_.
+10. If your pull request is accepted, all your commits will be squashed into one, and the `Conventional Commits Format <https://www.conventionalcommits.org/>`_ will be used on the commit message.
 
 Pull Request Guidelines
 -----------------------

diff --git a/Makefile b/Makefile
@@ -5,9 +5,9 @@ SOURCEDIR     = docs
 BUILDDIR      = docs/_build
 RERUN_AFTER   = 4h
 
-.PHONY: help Makefile always-run pre-commit poetry sphinx pytest reset
+.PHONY: help Makefile always-run pre-commit poetry doc test force force-docs
 
-dev: always-run .cache/make/auto-pre-commit .cache/make/auto-poetry .cache/make/sphinx .cache/make/run .cache/make/pytest
+dev: always-run .cache/make/auto-pre-commit .cache/make/auto-poetry .cache/make/doc .cache/make/run .cache/make/test
 
 always-run:
 	@mkdir -p .cache/make
@@ -19,8 +19,10 @@ help:
 	@echo 'Extra commands:'
 	@echo '  pre-commit  to install and update pre-commit hooks'
 	@echo '  poetry      to update dependencies'
-	@echo '  sphinx      to build docs'
-	@echo '  pytest      to run tests'
+	@echo '  doc         to build documentation'
+	@echo '  test        to run tests'
+	@echo '  force       to force rebuild of all targets in this Makefile'
+	@echo '  force-docs  to force rebuild of documentation'
 
 pre-commit:
 	-rm .cache/make/auto-pre-commit
@@ -41,37 +43,51 @@ poetry:
 .cache/make/auto-poetry: pyproject.toml
 	poetry update
 	poetry install
-	# Force creation of a setup.py to avoid this error on "pip install -e nitpick"
-	# ERROR: File "setup.py" not found. Directory cannot be installed in editable mode: ~/Code/nitpick
-	# (A "pyproject.toml" file was found, but editable mode currently requires a setup.py based build.)
-	# TODO remove this if ever pip changes this behaviour
+
+	@# Force creation of a setup.py to avoid this error on "pip install -e nitpick"
+	@# ERROR: File "setup.py" not found. Directory cannot be installed in editable mode: ~/Code/nitpick
+	@# (A "pyproject.toml" file was found, but editable mode currently requires a setup.py based build.)
+	@# Remove this if ever pip changes this behaviour
 	poetryx setup-py
+
 	touch .cache/make/auto-poetry
 	-rm .cache/make/run
 
-sphinx:
-	-rm .cache/make/sphinx
+doc: docs/* *.rst *.md
+	-rm .cache/make/doc
 	$(MAKE)
 
-# $(O) is meant as a shortcut for $(SPHINXOPTS).
-.cache/make/sphinx: docs *.rst *.md
+.cache/make/doc-source: src/*
 	-rm -rf docs/source
 	sphinx-apidoc --force --module-first --separate --implicit-namespaces --output-dir docs/source src/nitpick/
+	touch .cache/make/doc-source
+
+# $(O) is meant as a shortcut for $(SPHINXOPTS).
+.cache/make/doc: docs/* *.rst *.md .cache/make/doc-source
 	@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	touch .cache/make/sphinx
 
-.cache/make/run: .github/* .travis/* docs/* src/* styles/* tests/* nitpick-style.toml
+	@# Detect broken links on the documentation
+	@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -blinkcheck
+
+	touch .cache/make/doc
+
+.cache/make/run: .github/* .travis/* docs/**.py src/* styles/* tests/* nitpick-style.toml
 	pre-commit run --all-files
 	flake8
 	touch .cache/make/run
 
-pytest:
-	-rm .cache/make/pytest
+test:
+	-rm .cache/make/test
 	$(MAKE)
 
-.cache/make/pytest: src/* styles/* tests/*
+.cache/make/test: src/* styles/* tests/*
 	pytest
-	touch .cache/make/pytest
+	touch .cache/make/test
 
-reset:
-	rm -rf .cache/make
+force:
+	rm -rf .cache/make docs/_build docs/source
+	$(MAKE)
+
+force-docs:
+	rm -rf .cache/make/doc* docs/_build docs/source
+	$(MAKE)
diff --git a/README.md b/README.md
@@ -1,34 +1,24 @@
 # Nitpick
 
-[default style file]: (https://raw.githubusercontent.com/andreoliwa/nitpick/v0.20.0/nitpick-style.toml)
-[TOML]: (https://github.com/toml-lang/toml)
-[flake8]: (https://gitlab.com/pycqa/flake8)
-[isort]: (https://github.com/timothycrosley/isort)
-[black]: (https://github.com/psf/black)
-[mypy]: (http://mypy-lang.org/)
-[pylint]: (https://www.pylint.org)
-[pre-commit]: (https://pre-commit.com/)
-[poetry]: (https://github.com/sdispater/poetry/)
-
-[![PyPI](https://img.shields.io/pypi/v/nitpick.svg)](https://pypi.python.org/pypi/nitpick)
-[![Travis CI](https://travis-ci.com/andreoliwa/nitpick.svg)](https://travis-ci.com/andreoliwa/nitpick)
+[![PyPI](https://img.shields.io/pypi/v/nitpick.svg)](https://pypi.org/project/nitpick)
+[![Travis CI](https://api.travis-ci.com/andreoliwa/nitpick.svg)](https://travis-ci.com/andreoliwa/nitpick)
 [![Documentation Status](https://readthedocs.org/projects/nitpick/badge/?version=latest)](https://nitpick.readthedocs.io/en/latest/?badge=latest)
 [![Coveralls](https://coveralls.io/repos/github/andreoliwa/nitpick/badge.svg)](https://coveralls.io/github/andreoliwa/nitpick)
-[![Maintainability](https://api.codeclimate.com/v1/badges/61e0cdc48e24e76a0460/maintainability)](https://codeclimate.com/github/andreoliwa/nitpick/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/61e0cdc48e24e76a0460/test_coverage)](https://codeclimate.com/github/andreoliwa/nitpick/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/61e0cdc48e24e76a0460/maintainability)](https://codeclimate.com/github/andreoliwa/nitpick)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/61e0cdc48e24e76a0460/test_coverage)](https://codeclimate.com/github/andreoliwa/nitpick)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/nitpick.svg)](https://pypi.org/project/nitpick/)
 [![Project License](https://img.shields.io/pypi/l/nitpick.svg)](https://pypi.org/project/nitpick/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=andreoliwa/nitpick)](https://dependabot.com)
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 
-Flake8 plugin to enforce the same tool configuration ([flake8], [isort], [mypy], [pylint]...) across multiple Python projects.
+Flake8 plugin to enforce the same tool configuration ([flake8](https://gitlab.com/pycqa/flake8), [isort](https://github.com/timothycrosley/isort), [mypy](http://mypy-lang.org/), [Pylint](https://www.pylint.org)...) across multiple Python projects.
 
 Useful if you maintain multiple projects and want to use the same configs in all of them.
 
 ## Style file
 
-A "nitpick code style" is a [TOML] file with the settings that should be present in config files from other tools.
+A "nitpick code style" is a [TOML](https://github.com/toml-lang/toml) file with the settings that should be present in config files from other tools.
 
 Example of a style:
 
@@ -54,9 +44,9 @@ combine_as_imports = true
 
 This style will assert that:
 
-- ... [black], [isort] and [flake8] have a line length of 120;
-- ... [flake8] and [isort] are configured as above in `setup.cfg`;
-- ... [pylint] is present as a project dev dependency (in `pyproject.toml`, used by [poetry]).
+- ... [black](https://github.com/psf/black), [isort](https://github.com/timothycrosley/isort) and [flake8](https://gitlab.com/pycqa/flake8) have a line length of 120;
+- ... [flake8](https://gitlab.com/pycqa/flake8) and [isort](https://github.com/timothycrosley/isort) are configured as above in `setup.cfg`;
+- ... [Pylint](https://www.pylint.org) is present as a [Poetry](https://github.com/sdispater/poetry/) dev dependency in `pyproject.toml`).
 
 ## Quick setup
 
@@ -65,13 +55,13 @@ To try the package, simply install it (in a virtualenv or globally, wherever) an
     $ pip install -U nitpick
     $ flake8
 
-`nitpick` will use the opinionated [default style file].
+Nitpick will download and use the opinionated [default style file](https://raw.githubusercontent.com/andreoliwa/nitpick/v0.20.0/nitpick-style.toml).
 
-You can use it as a template to create your own style.
+You can use it as a template to configure your own style.
 
 ### Run as a pre-commit hook (recommended)
 
-If you use [pre-commit] on your project (you should), add this to the `.pre-commit-config.yaml` in your repository:
+If you use [pre-commit](https://pre-commit.com/) on your project (you should), add this to the `.pre-commit-config.yaml` in your repository:
 
     repos:
       - repo: https://github.com/andreoliwa/nitpick

diff --git a/docs/auto_detection.rst b/docs/auto_detection.rst
@@ -0,0 +1,40 @@
+.. include:: targets.rst
+
+.. _auto_detection:
+
+Auto-detection
+==============
+
+Root dir of the project
+-----------------------
+
+Nitpick_ tries to find the root dir of the project using some hardcoded assumptions.
+
+#. Starting from the current working directory, it will search for files that are usually in the root of a Python project:
+
+    - ``pyproject.toml``
+    - ``setup.py``
+    - ``setup.cfg``
+    - ``requirements*.txt``
+    - ``Pipfile`` (Pipenv_)
+    - ``app.py`` and ``wsgi.py`` (`Flask CLI`_)
+    - ``autoapp.py``
+
+#. If none of these root files were found, search for ``manage.py``.
+   On Django_ projects, it can be in another dir inside the root dir (:issue:`21`).
+#. If multiple roots are found, get the top one in the dir tree.
+
+Main Python file
+----------------
+
+After finding the `root dir of the project`_, Nitpick searches for a
+main Python file.
+Every project must have at least one ``*.py`` file, otherwise flake8_ won't even work.
+
+Those are the Python files that are considered:
+
+- ``setup.py``
+- ``app.py`` and ``wsgi.py`` (`Flask CLI`_)
+- ``autoapp.py``
+- ``manage.py``
+- any ``*.py`` file
diff --git a/docs/conf.py b/docs/conf.py
@@ -66,7 +66,8 @@
 source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = "index"
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-master_doc
+master_doc = "contents"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -83,6 +84,20 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky
+nitpicky = True
+
+# Ignore warning for these classes generated by autodoc,
+# but that could not be found in the "intersphinx_mapping" above.
+nitpick_ignore = [
+    ("py:class", "bool|tuple"),
+    ("py:class", "callable"),
+    ("py:class", "marshmallow.schema.Schema"),
+    ("py:class", "marshmallow.schema.SchemaOpts"),
+    ("py:class", "Schema"),
+    ("py:class", "ValidationError"),
+    ("py:exc", "ValidationError"),
+]
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -112,6 +127,8 @@
 #
 # html_sidebars = {}
 
+# https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=nitpicky#confval-html_last_updated_fmt
+html_last_updated_fmt = ""
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -191,7 +208,10 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "marshmallow": ("https://marshmallow.readthedocs.io/en/3.0/", None),
+}
 
 # -- Options for to do extension ----------------------------------------------
 
@@ -205,7 +225,7 @@
 autoclass_content = "both"
 
 # http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options
-autodoc_default_options = {"members": None, "inherited-members": None, "show-inheritance": None}
+autodoc_default_options = {"members": True, "inherited-members": True, "show-inheritance": True}
 
 # -- Options for autosummary extension ---------------------------------------
 

diff --git a/docs/contents.rst b/docs/contents.rst
@@ -0,0 +1,85 @@
+.. include:: targets.rst
+
+Nitpick
+=======
+
+.. image:: https://img.shields.io/pypi/v/nitpick.svg
+    :target: https://pypi.org/project/nitpick/
+    :alt: PyPI
+.. image:: https://api.travis-ci.com/andreoliwa/nitpick.svg
+    :target: https://travis-ci.com/andreoliwa/nitpick
+    :alt: Travis CI
+.. image:: https://readthedocs.org/projects/nitpick/badge/?version=latest
+    :target: https://nitpick.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+.. image:: https://coveralls.io/repos/github/andreoliwa/nitpick/badge.svg
+    :target: https://coveralls.io/github/andreoliwa/nitpick
+    :alt: Coveralls
+.. image:: https://api.codeclimate.com/v1/badges/61e0cdc48e24e76a0460/maintainability
+    :target: https://codeclimate.com/github/andreoliwa/nitpick
+    :alt: Maintainability
+.. image:: https://api.codeclimate.com/v1/badges/61e0cdc48e24e76a0460/test_coverage
+    :target: https://codeclimate.com/github/andreoliwa/nitpick
+    :alt: Test Coverage
+.. image:: https://img.shields.io/pypi/pyversions/nitpick.svg
+    :target: https://pypi.org/project/nitpick/
+    :alt: Supported Python versions
+.. image:: https://img.shields.io/pypi/l/nitpick.svg
+    :target: https://pypi.org/project/nitpick/
+    :alt: Project License
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+    :alt: Code style: black
+.. image:: https://api.dependabot.com/badges/status?host=github&repo=andreoliwa/nitpick
+    :target: https://dependabot.com
+    :alt: Dependabot Status
+.. image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
+    :target: https://github.com/semantic-release/semantic-release
+    :alt: semantic-release
+
+Flake8 plugin to enforce the same tool configuration (flake8_, isort_, mypy_, Pylint_...) across multiple Python projects.
+
+Useful if you maintain multiple projects and want to use the same configs in all of them.
+
+.. note::
+
+    This project is still a work in progress, so the API is not fully defined:
+
+        - :ref:`the-style-file` syntax might have changes before the 1.0 stable release.
+        - The numbers in the ``NIP*`` error codes might change; don't fully rely on them.
+
+.. toctree::
+   :caption: Contents:
+
+   installation_guide
+   styles
+   troubleshooting
+   contributing
+   authors
+
+.. toctree::
+   :caption: Configuration:
+
+   auto_detection
+   tool_nipick
+   nitpick_section
+   setup_cfg
+   defaults
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API:
+
+   source/modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+To Do List
+==========
+
+.. todolist::