Initial commit

Author: virtuald

.github/workflows/dist.yml

@@ -0,0 +1,38 @@
+---
+name: dist
+
+on: [push, pull_request]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v1
+      with:
+        python-version: 3.8
+    - name: Black
+      run: |
+        pip install black
+        black --check --diff .
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: [check]
+    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v1
+      with:
+        python-version: 3.8
+    - run: pip install wheel
+
+    - name: Build packages
+      run: python setup.py sdist bdist_wheel
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@master
+      with:
+        user: __token__
+        password: ${{ secrets.pypi_password }}

.gitignore

@@ -0,0 +1,8 @@
+*.pyc
+__pycache__
+*.egg-info
+
+.vscode
+
+/build
+/dist

README.md

@@ -0,0 +1,6 @@
+robotpy-sphinx-plugin
+=====================
+
+Common sphinx tooling for RobotPy projects.
+
+TODO docs for this repo

pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ['setuptools>=43', 'wheel', 'setuptools_scm==3.3.3']
+
+[tool.black]
+target-version = ['py36']
+exclude = '''
+(
+  /(
+      \.eggs         # exclude a few common directories in the
+    | \.git          # root of the project
+    | \.hg
+    | \.mypy_cache
+    | \.nox
+    | \.tox
+    | \.venv
+    | _build
+    | buck-out
+    | build
+    | dist
+  )/
+)
+'''

robotpy_sphinx/__init__.py

@@ -0,0 +1,11 @@
+"""
+    Includes sphinx extensions useful for all robotpy projects
+"""
+
+
+def setup(app):
+    from . import pybind11_fixer
+
+    app.setup_extension(pybind11_fixer.__name__)
+    app.setup_extension("sphinx_autodoc_typehints")
+    app.setup_extension("sphinx_automodapi.smart_resolver")

robotpy_sphinx/all.py

@@ -0,0 +1,21 @@
+import sphinx.addnodes
+
+
+def process_child(node):
+
+    if isinstance(node, sphinx.addnodes.desc_parameterlist) and node.children:
+        first_child = node.children[0]
+        if first_child.children and str(first_child.children[0]).startswith("self:"):
+            node.children = node.children[1:]
+
+    for child in node.children:
+        process_child(child)
+
+
+def doctree_read(app, doctree):
+    for child in doctree.children:
+        process_child(child)
+
+
+def setup(app):
+    app.connect("doctree-read", doctree_read)

robotpy_sphinx/pybind11_fixer.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""
+    A custom documentation generator because sphinx-apidoc doesn't quite do
+    what I want it to. The autosummary thing is really close to what I want.
+    However, the documentation for how to use it is lacking.
+    
+    This is designed to generate docs for our flat import structure in a
+    manner that is friendly to the readthedocs theme.
+"""
+
+import fnmatch
+import inspect
+import os
+import sys
+
+from os.path import abspath, join, dirname, exists
+from .utils import write_if_changed
+
+from sphinx_automodapi.utils import find_mod_objs
+
+mod_doc = """
+%(header)s
+
+%(fnlink)s
+
+.. autosummary::
+    %(names)s
+
+.. toctree::
+    :hidden:
+    
+    %(files)s
+
+"""
+
+cls_doc = """
+%(header)s
+
+.. autoclass:: %(package_name)s.%(cls_name)s
+    :members:
+    :undoc-members:
+    :show-inheritance:
+"""
+
+
+def _heading(name, c):
+    return "%s\n%s" % (name, c * len(name))
+
+
+def gen_package(root: str, package_name: str, exclude=None):
+    """
+        Writes rst files describing a package
+    """
+
+    if not exclude:
+        exclude = []
+
+    found = find_mod_objs(package_name)
+
+    docdir = abspath(join(root, package_name))
+    fnrst = abspath(join(root, package_name, "functions.rst"))
+    pkgrst = abspath(join(root, f"{package_name}.rst"))
+
+    old_files = {}
+    if exists(docdir):
+        for fname in os.listdir(docdir):
+            old_files[join(docdir, fname)] = True
+    else:
+        os.mkdir(docdir)
+
+    classes = []
+    functions = []
+
+    for name, _, obj in zip(*found):
+
+        excluded = False
+        for pattern in exclude:
+            if fnmatch.fnmatch(name, pattern):
+                excluded = True
+                break
+
+        if excluded:
+            continue
+
+        if inspect.isclass(obj):
+            fname = join(docdir, f"{name}.rst")
+            write_if_changed(
+                fname,
+                cls_doc
+                % {
+                    "header": _heading(name, "-"),
+                    "package_name": package_name,
+                    "cls_name": name,
+                },
+            )
+
+            old_files.pop(fname, None)
+            classes.append(name)
+
+        elif inspect.isroutine(obj):
+            functions.append(name)
+
+    classes = sorted(classes)
+    functions = sorted(functions)
+
+    # Create toctree
+
+    names = ["%s.%s" % (package_name, clsname) for clsname in classes]
+    files = ["%s/%s" % (package_name, clsname) for clsname in classes]
+    fnlink = ""
+
+    if functions:
+        files.insert(0, f"{package_name}/functions")
+        fnlink = f":doc:`{package_name} functions <{package_name}/functions>`"
+
+        functions_doc = _heading(f"{package_name} functions", "-").split("\n")
+        for fn in functions:
+            functions_doc.extend(
+                ["", f".. autofunction:: {package_name}.{fn}" "",]
+            )
+
+        write_if_changed(fnrst, "\n".join(functions_doc))
+        old_files.pop(fnrst, None)
+
+    write_if_changed(
+        pkgrst,
+        mod_doc
+        % {
+            "header": _heading(package_name + " Package", "="),
+            "fnlink": fnlink,
+            "module": package_name,
+            "names": "\n    ".join(names),
+            "files": "\n    ".join(files),
+        },
+    )
+
+    old_files.pop(pkgrst, None)
+
+    # delete any files that were not written, since this is an autogenerated directory
+    for fname in old_files.keys():
+        os.unlink(fname)

robotpy_sphinx/regen.py

@@ -0,0 +1,68 @@
+#
+# This file generates the sidebar/toctree for all RobotPy projects and should
+# be copied to each project when it is updated
+#
+
+import os
+import os.path
+import toml
+
+from .utils import write_if_changed
+import urllib.request
+
+
+def generate_sidebar(
+    conf, this_project, url, out="_sidebar.inc.rst", cfg="_sidebar.toml", lang="en"
+):
+    """
+        Call this from your sphinx project's conf.py::
+
+            generate_sidebar(globals(), "name", "url")
+
+        Your toplevel index.rst should have something like this:
+
+            .. include:: _sidebar.rst.inc
+    """
+
+    # determine 'latest' or 'stable'
+    force_dl = conf["on_rtd"]
+    do_gen = os.environ.get("SIDEBAR", None) == "1" or conf["on_rtd"]
+    version = conf["rtd_version"]
+
+    lines = ["", ".. DO NOT MODIFY! THIS PAGE IS AUTOGENERATED!", ""]
+
+    def toctree(name):
+        lines.extend([".. toctree::", f"    :caption: {name}", "    :maxdepth: 2", ""])
+
+    def endl():
+        lines.append("")
+
+    def write(project, desc, link):
+        if project == this_project:
+            args = desc, link
+        elif not do_gen:
+            return
+        else:
+            project_url = data["projects"][project]
+            args = (
+                desc,
+                f"{project_url}/{lang}/{version}/{link}.html",
+            )
+
+        lines.append("    %s <%s>" % args)
+
+    if force_dl or not os.path.exists(cfg):
+        urllib.request.urlretrieve(url, cfg)
+
+    with open(cfg) as fp:
+        data = toml.load(fp)
+
+    for tt in data["toctree"]:
+        toctree(tt["name"])
+
+        for item in tt["items"]:
+            write(item["p"], item["k"], item["v"])
+
+        endl()
+
+    write_if_changed("_sidebar.rst.inc", "\n".join(lines))

robotpy_sphinx/sidebar.py

@@ -0,0 +1,11 @@
+def write_if_changed(fname, contents):
+
+    try:
+        with open(fname, "r") as fp:
+            old_contents = fp.read()
+    except:
+        old_contents = ""
+
+    if old_contents != contents:
+        with open(fname, "w") as fp:
+            fp.write(contents)

robotpy_sphinx/utils.py

@@ -0,0 +1,32 @@
+[metadata]
+name = robotpy-sphinx-plugin
+description = Common Sphinx tooling for RobotPy projects
+long_description = file: README.md
+long_description_content_type = text/markdown
+author = Dustin Spicuzza
+author_email = [email protected]
+url = https://github.com/robotpy/robotpy-sphinx-plugin
+license = BSD-3-Clause
+classifiers =
+    Development Status :: 5 - Production/Stable
+    Intended Audience :: Developers
+    License :: OSI Approved :: BSD License
+    Programming Language :: Python :: 3 :: Only
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Topic :: Software Development
+
+[options]
+zip_safe = False
+include_package_data = True
+packages = find:
+install_requires =
+    setuptools >= 43
+    setuptools_scm == 3.3.3
+    sphinx-autodoc-typehints
+    sphinx-automodapi
+    toml
+setup_requires =
+    setuptools_scm
+python_requires = >=3.6

setup.cfg

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+
+from setuptools import setup
+
+setup(use_scm_version=True)