Ricordisamoa has uploaded a new change for review. ( https://gerrit.wikimedia.org/r/333367 )
Change subject: [WIP] README.rst and Sphinx documentation ...................................................................... [WIP] README.rst and Sphinx documentation Bug: T99847 Change-Id: I6438ae3594e6e60e6838cdd5b272438fd112abae --- A README.rst A docs/conf.py A docs/index.rst A docs/requirements.txt 4 files changed, 180 insertions(+), 0 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/labs/tools/ptable refs/changes/67/333367/1 diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..524881a --- /dev/null +++ b/README.rst @@ -0,0 +1,32 @@ +Wikidata periodic table +======================= + +Python 3.3 or later is required to run this program. Using `virtual environments`_ +(or `virtualenv`_) is strongly recommended. + +Installing dependencies for running the program: + +.. code:: sh + + pip install -r requirements.txt + +Installing dependencies for building the documentation: + +.. code:: sh + + pip install -r docs/requirements.txt + +Generating API documentation from docstrings: + +.. code:: sh + + sphinx-apidoc -f -o docs . + +Building the documentation: + +.. code:: sh + + sphinx-build -a docs docs/_build + +.. _virtual environments: https://docs.python.org/3/library/venv.html +.. _virtualenv: https://virtualenv.pypa.io diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..0510853 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,129 @@ +# -*- coding: utf-8 -*- +""" +Copyright © 2017 Ricordisamoa + +This file is part of the Wikidata periodic table. + +The Wikidata periodic table is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +The Wikidata periodic table is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with the Wikidata periodic table. If not, see <http://www.gnu.org/licenses/>. +""" +# +# Wikidata periodic table documentation build configuration file, created by +# sphinx-quickstart. + +# 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. +# +import os +import sys + + +sys.path.insert(0, os.path.abspath('..')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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'] + +# 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' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Wikidata periodic table' +copyright = '2012-2017, Wikidata periodic table contributors' +author = 'Wikidata periodic table contributors' + +# 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 = None + +# 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', 'Thumbs.db', '.DS_Store'] + +# 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 = False + + +# -- 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 = {} + +# 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'] + + +def autodoc_process_docstring(app, what, name, obj, options, lines): + """Strip copyright statement and all subsequent text from a module docstring.""" + if what != 'module': + return + deleted = 0 + delete = False + orig_lines = lines[:] + for i, line in enumerate(orig_lines): + if delete is False and line.startswith('Copyright ©'): + delete = True + if delete: + lines.pop(i - deleted) + deleted += 1 + # make sure there is a blank line at the end + if lines and lines[-1]: + lines.append('') + + +def setup(app): + app.connect('autodoc-process-docstring', autodoc_process_docstring) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..048fd5d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,18 @@ +Welcome to the Wikidata periodic table's documentation! +======================================================= + +Modules +------- + +.. toctree:: + :maxdepth: 2 + + modules + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..2806c16 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +Sphinx -- To view, visit https://gerrit.wikimedia.org/r/333367 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I6438ae3594e6e60e6838cdd5b272438fd112abae Gerrit-PatchSet: 1 Gerrit-Project: labs/tools/ptable Gerrit-Branch: master Gerrit-Owner: Ricordisamoa <ricordisa...@openmailbox.org> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
