diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 7293361..614661d 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,5 +1,5 @@ name: Build -on: +on: push: branches: - master @@ -35,3 +35,5 @@ jobs: - name: Coverage run: codecov --token ${{ secrets.CODECOV_TOKEN }} --branch ${{ github.ref }} continue-on-error: true + - name: Documentation + run: make html diff --git a/.gitignore b/.gitignore index f9db0b0..387c3a7 100644 --- a/.gitignore +++ b/.gitignore @@ -106,4 +106,5 @@ venv.bak/ # Visual Studio Code .vscode/ +html/ usort/version.py diff --git a/Makefile b/Makefile index 9b091ab..26a6174 100644 --- a/Makefile +++ b/Makefile @@ -7,6 +7,14 @@ venv: source .venv/bin/activate && make setup @echo 'run `source .venv/bin/activate` to use virtualenv' +.PHONY: clean +clean: + rm -rf dist html + +.PHONY: distclean +distclean: + rm -rf .venv + # The rest of these are intended to be run within the venv, where python points # to whatever was used to set up the venv. @@ -32,6 +40,10 @@ lint: python -m flake8 $(SOURCES) mypy --strict usort +.PHONY: html +html: + sphinx-build -b html docs html + .PHONY: release release: rm -rf dist diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000..3a94175 --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,20 @@ +div.facebook { + margin-top: 24px; +} + +div.facebook-badges { + margin-top: 12px; + margin-bottom: 10px; +} + +div.facebook-badges a { + color: #bbb; + text-decoration: none; + font-size: 24px; + border: none; +} + +div.facebook a, div.facebook a:hover, div.facebook-badges a:hover { + color: #777; + border: none; +} diff --git a/docs/_static/fbopensource.png b/docs/_static/fbopensource.png new file mode 100644 index 0000000..2b5480d Binary files /dev/null and b/docs/_static/fbopensource.png differ diff --git a/docs/_templates/badges.html b/docs/_templates/badges.html new file mode 100644 index 0000000..8850338 --- /dev/null +++ b/docs/_templates/badges.html @@ -0,0 +1,6 @@ +
+ Star +
+ + diff --git a/docs/_templates/facebook.html b/docs/_templates/facebook.html new file mode 100644 index 0000000..de7fdad --- /dev/null +++ b/docs/_templates/facebook.html @@ -0,0 +1,17 @@ +
+ + Facebook Open Source + +
+
+ + + +   + + + + +
+ + diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..83d7eb5 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,4 @@ +Changelog +========= + +.. mdinclude:: ../CHANGELOG.md diff --git a/docs/code-of-conduct.rst b/docs/code-of-conduct.rst new file mode 100644 index 0000000..8340f66 --- /dev/null +++ b/docs/code-of-conduct.rst @@ -0,0 +1,5 @@ +Code of Conduct +=============== + +.. mdinclude:: ../CODE_OF_CONDUCT.md + :start-line: 2 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..1fe90fe --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,91 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# 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. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +import datetime + +project = "µsort" +copyright = f"{datetime.date.today().year}, Facebook Inc." +author = "Tim Hatch" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "m2r", + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# 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 = [] + +autodoc_default_options = { + "show-inheritance": True, + "members": True, + "undoc-members": True, +} +autodoc_member_order = "groupwise" + +highlight_language = "python3" +intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} +master_doc = "index" + +# -- 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 = "alabaster" +html_theme_options = { + "description": "Safe Python import sorting", + "fixed_sidebar": True, + "badge_branch": "master", + "github_button": False, + "github_user": "facebookexperimental", + "github_repo": "usort", + "show_powered_by": False, + "sidebar_collapse": False, + "extra_nav_links": { + "Report Issues": "https://github.com/facebookexperimental/usort/issues", + }, +} + +html_sidebars = { + "**": [ + "about.html", + "badges.html", + "navigation.html", + "relations.html", + "searchbox.html", + "facebook.html", + ], +} + +# 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"] diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..6168c75 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,5 @@ +Contributing +============ + +.. mdinclude:: ../CONTRIBUTING.md + :start-line: 1 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..8f16b7f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,10 @@ +.. mdinclude:: ../README.md + + +.. toctree:: + :hidden: + :maxdepth: 1 + + changelog + contributing + code-of-conduct diff --git a/requirements-dev.txt b/requirements-dev.txt index 0479c95..2584352 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -3,7 +3,9 @@ coverage==4.5.4 flake8==3.7.9 isort==4.3.21 mypy==0.750 +sphinx==3.0.3 tox==3.14.1 twine==3.1.1 volatile==2.1.0 wheel==0.33.6 +git+https://github.com/miyakogi/m2r@66f4a5a500cdd9fc59085106bff082c9cadafaf3