From 426a03e850e2400732fb9688bfa8050312bfb702 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 15 Nov 2016 17:15:32 +0100 Subject: [PATCH] Update make targets for docs and add support for apidocs --- .gitignore | 2 ++ Makefile | 88 +++++++++++++++++++++++++++++++--------------------- docs/conf.py | 30 ++++++++++++++++-- 3 files changed, 82 insertions(+), 38 deletions(-) diff --git a/.gitignore b/.gitignore index 5c07e11f..98650662 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,8 @@ wiki/attachments #Docs docs/_build docs/_build/* +docs/wiki.* +docs/modules.rst # Test project testproject/testproject/settings/local.py diff --git a/Makefile b/Makefile index 53e858e7..c20cffe0 100644 --- a/Makefile +++ b/Makefile @@ -1,64 +1,82 @@ -.PHONY: help clean clean-pyc clean-build list test test-all coverage docs release sdist +.PHONY: clean clean-test clean-pyc clean-build docs help +.DEFAULT_GOAL := help +define BROWSER_PYSCRIPT +import os, webbrowser, sys +try: + from urllib import pathname2url +except: + from urllib.request import pathname2url + +webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1]))) +endef +export BROWSER_PYSCRIPT + +define PRINT_HELP_PYSCRIPT +import re, sys + +for line in sys.stdin: + match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line) + if match: + target, help = match.groups() + print("%-20s %s" % (target, help)) +endef +export PRINT_HELP_PYSCRIPT +BROWSER := python -c "$$BROWSER_PYSCRIPT" help: - @echo "clean-build - remove build artifacts" - @echo "clean-pyc - remove Python file artifacts" - @echo "lint - check style with flake8" - @echo "test - run tests quickly with the default Python" - @echo "testall - run tests on every Python version with tox" - @echo "coverage - check code coverage quickly with the default Python" - @echo "docs - generate Sphinx HTML documentation, including API docs" - @echo "release - package and upload a release" - @echo "sdist - package" - -clean: clean-build clean-pyc - -clean-build: + @python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST) + +clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts + + +clean-build: ## remove build artifacts rm -fr build/ rm -fr dist/ - rm -fr *.egg-info + rm -fr .eggs/ + find . -name '*.egg-info' -exec rm -fr {} + + find . -name '*.egg' -exec rm -f {} + -clean-pyc: +clean-pyc: ## remove Python file artifacts find . -name '*.pyc' -exec rm -f {} + find . -name '*.pyo' -exec rm -f {} + find . -name '*~' -exec rm -f {} + + find . -name '__pycache__' -exec rm -fr {} + + +clean-test: ## remove test and coverage artifacts + rm -fr .tox/ + rm -f .coverage + rm -fr htmlcov/ -lint: +lint: ## Check python code conventions pep8 wiki -test: +test: ## Run automated test suite pytest -test-all: +test-all: ## Run tests on all supported Python environments tox -coverage: +coverage: ## Generate test coverage report coverage run --source wiki setup.py test coverage report -m -docs: +docs: ## generate Sphinx HTML documentation, including API docs $(MAKE) -C docs clean + rm -f docs/wiki*.rst + rm -f docs/modules.rst + sphinx-build -b linkcheck ./docs ./docs/_build + sphinx-apidoc -o docs/ wiki $(MAKE) -C docs html - sphinx-build -b linkcheck ./docs _build/ - sphinx-build -b html ./docs _build/ + $(BROWSER) docs/_build/html/index.html -release: sdist +release: sdist ## Generate and upload release to PyPi twine upload -s dist/* -assets: +assets: ## Build CSS files lessc wiki/static/wiki/bootstrap/less/wiki/wiki-bootstrap.less wiki/static/wiki/bootstrap/css/wiki-bootstrap.css lessc -x wiki/static/wiki/bootstrap/less/wiki/wiki-bootstrap.less wiki/static/wiki/bootstrap/css/wiki-bootstrap.min.css -sdist: clean assets - # echo "Creating HISTORY.rst..." - # echo "Latest Changes" > HISTORY.rst - # echo "==============" >> HISTORY.rst - # echo "" >> HISTORY.rst - # echo "This file is auto-generated upon every new release." - # echo "" >> HISTORY.rst - # echo "Compiled on: `date`::" >> HISTORY.rst - # echo "" >> HISTORY.rst - # git log --graph --pretty=format:'%h -%d %s (%cr) <%an>' --abbrev-commit | sed "s/^/ /" >> HISTORY.rst +sdist: clean assets ## Generate source dist and wheels python setup.py sdist python setup.py bdist_wheel ls -l dist diff --git a/docs/conf.py b/docs/conf.py index ec3e89e9..f30654d4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,7 @@ # -*- coding: utf-8 -*- from __future__ import absolute_import, print_function, unicode_literals +from datetime import datetime import os import sys @@ -27,9 +28,28 @@ import sys # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' +import django + +# 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. + +sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../testproject')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +os.environ.setdefault("DJANGO_SETTINGS_MODULE", "testproject.settings.dev") + +django.setup() + + # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -45,7 +65,7 @@ master_doc = 'index' # General information about the project. project = 'django-wiki' -copyright = '2013, Benjamin Bach' # noqa +copyright = '{}, Benjamin Bach'.format(datetime.now().year) # noqa path = os.path.abspath(os.path.dirname(os.path.dirname(__file__))) @@ -62,7 +82,7 @@ import wiki # noqa # built documents. # # The short X.Y version. -version = ".".join(wiki.__version__.split(".")[:-1]) +version = ".".join(wiki.__version__.split(".")[0:100]) # The full version, including alpha/beta/rc tags. release = wiki.__version__ @@ -100,6 +120,10 @@ pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] +linkcheck_ignore = [ + r'wiki.+', +] + # -- Options for HTML output --------------------------------------------------- -- 2.45.2