diff --git a/.gitignore b/.gitignore index 6c12322..828b2b0 100644 --- a/.gitignore +++ b/.gitignore @@ -13,5 +13,5 @@ /__pycache__ /build /dist -/esedbrc.egg-info +/sqliterc.egg-info diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..d362401 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,170 @@ +# -*- coding: utf-8 -*- +"""Sphinx build configuration file.""" + +import os +import sys + +from sphinx.ext import apidoc + +from docutils import nodes +from docutils import transforms + +# Change PYTHONPATH to include sqliterc module and dependencies. +sys.path.insert(0, os.path.abspath('..')) + +import sqliterc # pylint: disable=wrong-import-position + +import utils.dependencies # pylint: disable=wrong-import-position + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '2.0.1' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'recommonmark', + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx.ext.doctest', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', + 'sphinx_markdown_tables', + 'sphinx_rtd_theme', +] + +# We cannot install architecture dependent Python modules on readthedocs, +# therefore we mock most imports. +pip_installed_modules = set() + +dependency_helper = utils.dependencies.DependencyHelper( + dependencies_file=os.path.join('..', 'dependencies.ini'), + test_dependencies_file=os.path.join('..', 'test_dependencies.ini')) +modules_to_mock = set(dependency_helper.dependencies.keys()) +modules_to_mock = modules_to_mock.difference(pip_installed_modules) + +autodoc_mock_imports = sorted(modules_to_mock) + +# Options for the Sphinx Napoleon extension, which reads Google-style +# docstrings. +napoleon_google_docstring = True +napoleon_numpy_docstring = False +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = True + +# General information about the project. +# pylint: disable=redefined-builtin +project = 'SQLite database knowledge base' +copyright = 'The SQLite database knowledge base authors' +version = sqliterc.__version__ +release = sqliterc.__version__ + +# 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. +exclude_patterns = ['_build'] + +# The master toctree document. +master_doc = 'index' + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- 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 = 'sphinx_rtd_theme' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'sqlitekbdoc' + + +# -- Options linkcheck ---------------------------------------------------- + +linkcheck_ignore = [ +] + + +# -- Code to rewrite links for readthedocs -------------------------------- + +# This function is a Sphinx core event callback, the format of which is detailed +# here: https://www.sphinx-doc.org/en/master/extdev/appapi.html#events + +# pylint: disable=unused-argument +def RunSphinxAPIDoc(app): + """Runs sphinx-apidoc to auto-generate documentation. + + Args: + app (sphinx.application.Sphinx): Sphinx application. Required by the + the Sphinx event callback API. + """ + current_directory = os.path.abspath(os.path.dirname(__file__)) + module_path = os.path.join(current_directory, '..', 'sqliterc') + api_directory = os.path.join(current_directory, 'sources', 'api') + apidoc.main(['-o', api_directory, module_path, '--force']) + + +class MarkdownLinkFixer(transforms.Transform): + """Transform definition to parse .md references to internal pages.""" + + default_priority = 1000 + + _URI_PREFIXES = [] + + def _FixLinks(self, node): + """Corrects links to .md files not part of the documentation. + + Args: + node (docutils.nodes.Node): docutils node. + + Returns: + docutils.nodes.Node: docutils node, with correct URIs outside + of Markdown pages outside the documentation. + """ + if isinstance(node, nodes.reference) and 'refuri' in node: + reference_uri = node['refuri'] + for uri_prefix in self._URI_PREFIXES: + if (reference_uri.startswith(uri_prefix) and not ( + reference_uri.endswith('.asciidoc') or + reference_uri.endswith('.md'))): + node['refuri'] = reference_uri + '.md' + break + + return node + + def _Traverse(self, node): + """Traverses the document tree rooted at node. + + Args: + node (docutils.nodes.Node): docutils node. + """ + self._FixLinks(node) + + for child_node in node.children: + self._Traverse(child_node) + + # pylint: disable=arguments-differ + def apply(self): + """Applies this transform on document tree.""" + self._Traverse(self.document) + + +# pylint: invalid-name +def setup(app): + """Called at Sphinx initialization. + + Args: + app (sphinx.application.Sphinx): Sphinx application. + """ + # Triggers sphinx-apidoc to generate API documentation. + app.connect('builder-inited', RunSphinxAPIDoc) + app.add_config_value( + 'recommonmark_config', {'enable_auto_toc_tree': True}, True) + app.add_transform(MarkdownLinkFixer) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..febbedd --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,9 @@ +Welcome to the sqlite-kb documentation +======================================== + +sqlite-kb is a project to build a SQLite database file Knowledge Base. + +sqliterc is a Python module part of sqlite-kb to allow reuse of SQLite database +Resources. + +The source code is available from the `project page `__. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..bbbfa6b --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +certifi >= 2023.11.17 +docutils +Markdown +recommonmark +sphinx >= 4.1.0 +sphinx-markdown-tables +sphinx-rtd-theme >= 0.5.1 diff --git a/docs/sources/api/modules.rst b/docs/sources/api/modules.rst new file mode 100644 index 0000000..2b7a2b6 --- /dev/null +++ b/docs/sources/api/modules.rst @@ -0,0 +1,7 @@ +sqliterc +======== + +.. toctree:: + :maxdepth: 4 + + sqliterc diff --git a/docs/sources/api/sqliterc.rst b/docs/sources/api/sqliterc.rst new file mode 100644 index 0000000..47fc054 --- /dev/null +++ b/docs/sources/api/sqliterc.rst @@ -0,0 +1,37 @@ +sqliterc package +================ + +Submodules +---------- + +sqliterc.resources module +------------------------- + +.. automodule:: sqliterc.resources + :members: + :undoc-members: + :show-inheritance: + +sqliterc.schema\_extractor module +--------------------------------- + +.. automodule:: sqliterc.schema_extractor + :members: + :undoc-members: + :show-inheritance: + +sqliterc.yaml\_definitions\_file module +--------------------------------------- + +.. automodule:: sqliterc.yaml_definitions_file + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: sqliterc + :members: + :undoc-members: + :show-inheritance: diff --git a/tox.ini b/tox.ini index 13c9764..28eabcd 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = py3{7,8,9,10,11,12},coverage,lint,wheel +envlist = py3{7,8,9,10,11,12},coverage,docs,lint,wheel [testenv] allowlist_externals = ./run_tests.py @@ -25,6 +25,14 @@ commands = coverage: coverage xml wheel: python -m build --no-isolation --wheel +[testenv:docs] +usedevelop = True +deps = + -rdocs/requirements.txt +commands = + sphinx-build -b html -d build/doctrees docs dist/docs + sphinx-build -b linkcheck docs dist/docs + [testenv:lint] skipsdist = True pip_pre = True