diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..fe28f4b --- /dev/null +++ b/.editorconfig @@ -0,0 +1,31 @@ +# -*- coding: utf-8 -*- + +root = true + +[*] +indent_style = space +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +charset = utf-8 + +# Python files +[*.py] +indent_size = 4 +# isort plugin configuration +known_first_party = sphinxcontrib +multi_line_output = 2 +default_section = THIRDPARTY +skip = .eggs docs + +# .travis.yml +[.travis.yml] +indent_size = 2 + +# Dockerfile +[Dockerfile] +indent_size = 4 + +# Makefile +[Makefile] +indent_size = 4 diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 0000000..c411450 --- /dev/null +++ b/.github/workflows/ci.yaml @@ -0,0 +1,34 @@ +name: Python CI + +on: [push, pull_request] + +jobs: + build: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: [3.8, 3.9, 3.10, 3.11, 3.12] + + steps: + - uses: actions/checkout@v2 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + + - name: Install dependencies + run: | + pip install -e .[develop] + + - name: Run tests with pytest + run: pytest + + - name: Run type checks with mypy + run: mypy sphinxcontrib + + - name: Run style checks + run: | + isort --check-only --diff sphinxcontrib tests + yapf --diff sphinxcontrib tests + flake8 sphinxcontrib tests diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ac7d049 --- /dev/null +++ b/.gitignore @@ -0,0 +1,49 @@ +*.py[cod] + +# C extensions +*.so + +# Packages +*.egg* +*.egg-info +dist +build +eggs +parts +bin +var +sdist +develop-eggs +.installed.cfg +lib +lib64 + +# Installer logs +pip-log.txt + +# Unit test / coverage reports +cover/ +.coverage* +.tox +.venv +.pytest_cache/ +.mypy_cache/ + +# Translations +*.mo + +# Complexity +output/*.html +output/*/index.html + +# Sphinx +doc/build + +# pbr +AUTHORS +ChangeLog + +# Editors +*~ +.*.swp +.*sw? diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..a22f307 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,27 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.0.1 # Use the latest version from the pre-commit-hooks repository + hooks: + - id: check-yaml + - id: end-of-file-fixer + - id: trailing-whitespace + + - repo: https://github.com/pycqa/flake8 + rev: 4.0.1 # Use the latest version of flake8 + hooks: + - id: flake8 + + - repo: https://github.com/pre-commit/mirrors-isort + rev: v5.10.1 # Use the latest version of isort + hooks: + - id: isort + + - repo: https://github.com/asottile/black + rev: 22.3.0 # Use the latest version of black + hooks: + - id: black + + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v0.931 # Use the latest version of mypy + hooks: + - id: mypy diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..e1095ce --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,10 @@ +============== + Contributing +============== + +If you would like to contribute to this project, or any project in the +`sphinx-contrib`_ namespace, you should refer to the guidelines found in the +`Sphinx documentation`_. + +.. _sphinx-contrib: https://github.com/sphinx-contrib +.. _Sphinx documentation: https://www.sphinx-doc.org/en/master/internals/contributing diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3583a0e --- /dev/null +++ b/LICENSE @@ -0,0 +1,25 @@ +Copyright (c) 2018 by daquintero +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4c643b7 --- /dev/null +++ b/README.md @@ -0,0 +1,12 @@ +# sphinxcontrib-autoflex + +A flexible, nicer way of generating API docs without requiring custom docstrings. + +## Overview + +Add a longer description here. + +## Links + +- Source: +- Bugs: diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..8aec2e3 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,61 @@ +[tool.poetry] +name = "sphinxcontrib-autoflex" +version = "0.0.1" +description = "A flexible, nicer way of generating API docs without requiring custom docstrings." +authors = ["daquintero "] +homepage = "http://www.sphinx-doc.org/" +license = "BSD" # Replace with your project's license, if different +classifiers = [ + "Development Status :: 3 - Alpha", + "Environment :: Console", + "Environment :: Web Environment", + "Framework :: Sphinx :: Extension", + "Intended Audience :: Developers", + "License :: OSI Approved :: BSD License", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.6", + "Programming Language :: Python :: 3.7", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Topic :: Documentation", + "Topic :: Documentation :: Sphinx", + "Topic :: Utilities" +] + + +[tool.poetry.dependencies] +python = "^3.6" +pbr = "^5.5.1" + +pytest = {version="*", optional=true} +sphinx = {version="*", optional=true} +mypy = {version="*", optional=true} +flake8 ={version="*", optional=true} + +[tool.poetry.extras] +develop = [ + "pytest", + "sphinx", + "mypy", + "flake8" +] + +[build-system] +requires = ["poetry-core>=1.0.0"] +build-backend = "poetry.core.masonry.api" + +[tool.mypy] +python_version = "3.8" +show_column_numbers = true +show_error_context = true +ignore_missing_imports = true +follow_imports = "skip" +incremental = true +check_untyped_defs = true +warn_unused_ignores = true + +[tool.flake8] +show-source = true +builtins = "unicode" diff --git a/sphinxcontrib/__init__.py b/sphinxcontrib/__init__.py new file mode 100644 index 0000000..ae0f862 --- /dev/null +++ b/sphinxcontrib/__init__.py @@ -0,0 +1,12 @@ +""" + sphinxcontrib + ~~~~~~~~~~~~~ + + This package is a namespace package that contains all extensions + distributed in the ``sphinx-contrib`` distribution. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +__import__('pkg_resources').declare_namespace(__name__) diff --git a/sphinxcontrib/autoflex/__init__.py b/sphinxcontrib/autoflex/__init__.py new file mode 100644 index 0000000..854ac5a --- /dev/null +++ b/sphinxcontrib/autoflex/__init__.py @@ -0,0 +1,24 @@ +""" + sphinxcontrib.autoflex + ~~~~~~~~~~~~~~~~~~~~~~ + + A flexible, nicer way of generating API docs without requiring custom docstrings. + + :copyright: Copyright 2017 by daquintero + :license: BSD, see LICENSE for details. +""" + +import pbr.version + +if False: + # For type annotations + from typing import Any, Dict # noqa + from sphinx.application import Sphinx # noqa + +__version__ = pbr.version.VersionInfo( + 'autoflex').version_string() + + +def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] + return {'version': __version__, 'parallel_read_safe': True} diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..47604da --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,9 @@ +""" + pytest config for sphinxcontrib/autoflex/tests + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + :copyright: Copyright 2017 by daquintero + :license: BSD, see LICENSE for details. +""" + +pytest_plugins = 'sphinx.testing.fixtures'