diff --git a/.gitignore b/.gitignore index f5fc2ae..cb16d33 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,10 @@ *.pyc *.sw? *~ .coverage .eggs/ __pycache__ *.egg-info/ -version.txt \ No newline at end of file +version.txt +.tox +docs/apidoc diff --git a/docs/Makefile b/docs/Makefile index 5a1770d..8c2f78b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,63 +1,71 @@ SPHINXOPTS = SPHINXBUILD = python3 -c 'import sphinx, sys; sys.exit(sphinx.main(sys.argv))' SOURCEDIR = . BUILDDIR = _build HTMLDIR = $(BUILDDIR)/html +SWHPKGDIR = `python3 -c 'import swh; print(swh.__path__[0])'` INSTALL_HOST = pergamon.internal.softwareheritage.org INSTALL_DIR = /srv/softwareheritage/docs/webroot/devel INSTALL_GROUP = swhdev INSTALL_PERMS = g+rwX -html: fix-indices-stamp sphinx/html +SPHINXAPIDOC = sphinx-apidoc +APIDOC_DIR = apidoc +APIDOC_OPTS = --ext-viewcode +APIDOC_EXCLUDES = */tests */tests/* */*/tests/* */*/*/tests/* +APIDOC_EXCLUDES += */migrations */migrations/* */*/migrations/* */*/*/migrations/* +APIDOC_SWH_EXCLUDES = $(patsubst %,$(SWHPKGDIR)/%,$(APIDOC_EXCLUDES)) -fix-indices-stamp: sphinx/html - bin/copy-and-fix-subprojects-indices - touch $@ +apidoc_dep = apidoc-stamp + +html: sphinx/html sphinx/html: links-stamp apidoc-stamp images-stamp rec-build-stamp links-stamp: bin/ln-sphinx-subprojects touch $@ +apidoc: $(apidoc_dep) apidoc-stamp: - $(MAKE) -C ../../ docs-apidoc + $(SPHINXAPIDOC) $(APIDOC_OPTS) -o $(APIDOC_DIR) $(SWHPKGDIR) $(APIDOC_SWH_EXCLUDES) touch $@ images-stamp: $(MAKE) -C images touch $@ # Build documentation recursively in all packages, to make sure that auxiliary, # non-sphinx managed documentation artifacts (e.g., schema diagrams) are also # built. rec-build-stamp: $(wildcard ../../swh-*/docs/*.rst) - $(MAKE) -C ../../ docs + $(MAKE) -C ../../ docs-assets touch $@ clean: sphinx/clean bin/ln-sphinx-subprojects --remove $(MAKE) -C images clean rm -f *-stamp + rm -f $(APIDOC_DIR)/* distclean: clean make -C ../../ docs-clean help: sphinx/help sphinx/clean: @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) sphinx/%: @$(SPHINXBUILD) -b $* "$(SOURCEDIR)" "$(BUILDDIR)/$*" $(SPHINXOPTS) install: html test -d $(HTMLDIR) rsync -rlvuz --delete $(BUILDDIR)/html/ $(INSTALL_HOST):$(INSTALL_DIR)/ ssh $(INSTALL_HOST) \ "find $(INSTALL_DIR) -not -group $(INSTALL_GROUP) -exec chgrp -v $(INSTALL_GROUP) {} + ; \ find $(INSTALL_DIR) -not -perm -ug=rw,o=r -exec chmod -v ug+rw,o+r {} + ; \ find $(INSTALL_DIR) -type d -not -perm -g=xs,ou=x -exec chmod -v g+xs,ou+x {} +" .PHONY: help html clean distclean install diff --git a/requirements-swh.txt b/requirements-swh.txt index 2d1bbce..6d15419 100644 --- a/requirements-swh.txt +++ b/requirements-swh.txt @@ -1 +1,22 @@ # Add here internal Software Heritage dependencies, one per line. +swh-core +swh-model +swh-objstorage[testing] +swh-scheduler +swh-storage[schemadata] +swh-loader-core +swh-lister +swh-journal +swh-vault +swh-loader-dir +swh-loader-tar +swh-loader-pypi +swh-loader-debian +swh-loader-mercurial +swh-loader-svn +swh-loader-git +swh-archiver +swh-web +swh-deposit +swh-indexer +swh-mirror-forge diff --git a/swh/docs/django_settings.py b/swh/docs/django_settings.py new file mode 100644 index 0000000..07a9a3c --- /dev/null +++ b/swh/docs/django_settings.py @@ -0,0 +1,4 @@ +#from swh.web.settings.development import * # noqa +from swh.deposit.settings.development import * # noqa + +SECRET_KEY = 'change me' diff --git a/swh/docs/sphinx/conf.py b/swh/docs/sphinx/conf.py index 41e8c49..23ed0b8 100755 --- a/swh/docs/sphinx/conf.py +++ b/swh/docs/sphinx/conf.py @@ -1,144 +1,141 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # import django import os # General information about the project. project = 'Software Heritage - Development Documentation' copyright = '2015-2018, the Software Heritage developers' author = 'the Software Heritage developers' # -- 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 = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinxcontrib.httpdomain', 'sphinx.ext.extlinks', 'sphinxcontrib.images', + 'sphinx.ext.viewcode', ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # source_suffix = ['.rst', '.md'] # source_suffix = '.rst' source_parsers = { '.md': 'recommonmark.parser.CommonMarkParser', } # The master toctree document. master_doc = 'index' # A string of reStructuredText that will be included at the beginning of every # source file that is read. +# A bit hackish but should work both for each swh package and the whole swh-doc rst_prolog = ''' -.. include:: /swh_substitutions +.. include:: /../../swh-docs/docs/swh_substitutions ''' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = '' # The full version, including alpha/beta/rc tags. release = '' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path exclude_patterns = ['_build'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True # -- 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' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # html_theme_options = { 'logo': 'software-heritage-logo-title-motto-vertical.svg', 'font_family': "'Alegreya Sans', sans-serif", 'head_font_family': "'Alegreya', serif", # equivalent of alabaster's: 'gray_1': '#5b5e6f', # dark gray 'gray_2': '#efeff2', # light gray 'gray_3': '#b1b5ae', # medium gray 'pink_1': '#e5d4cf', # light pink 'pink_2': '#bd9f97', # medium pink 'fixed_sidebar': 'true', } # 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'] # make logo actually appear, avoiding gotcha due to alabaster default conf. # https://github.com/bitprophet/alabaster/issues/97#issuecomment-303722935 html_sidebars = { '**': [ 'about.html', 'localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html', ] } # refer to the Python standard library. intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} # -- autodoc configuration ---------------------------------------------- autodoc_default_flags = ['members', 'undoc-members'] autodoc_member_order = 'bysource' autodoc_mock_imports = ['rados'] # for the extlinks extension, sub-projects should fill that dict extlinks = {} # hack to set the adequate django settings when building global swh doc # to avoid build errors def source_read_handler(app, docname, source): - if 'swh-deposit' in docname: - os.environ.setdefault('DJANGO_SETTINGS_MODULE', - 'swh.deposit.settings.development') - django.setup() - elif 'swh-web' in docname: - os.environ.setdefault('DJANGO_SETTINGS_MODULE', - 'swh.web.settings.development') - django.setup() + os.environ.setdefault('DJANGO_SETTINGS_MODULE', + 'swh.docs.django_settings') + django.setup() def setup(app): app.connect('source-read', source_read_handler) diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..c58ec85 --- /dev/null +++ b/tox.ini @@ -0,0 +1,17 @@ +[tox] +envlist=flake8 + +[testenv:sphinx] +deps = + django < 2 + .[testing] + pifpaf +commands = + {envpython} -m pifpaf run postgresql -- make -C docs html + +[testenv:flake8] +skip_install = true +deps = + flake8 +commands = + {envpython} -m flake8