diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 7422f7c8..4fb1a267 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -1,6 +1,15 @@
version: 2
updates:
+ # Maintain dependencies for pip
+ - package-ecosystem: "pip"
+ directory: "/"
+ schedule:
+ interval: "daily"
+ assignees:
+ - "LeMyst"
+ open-pull-requests-limit: 10
+
# Maintain dependencies for GitHub Actions
- package-ecosystem: "github-actions"
directory: "/"
@@ -8,11 +17,13 @@ updates:
interval: "daily"
assignees:
- "LeMyst"
+ open-pull-requests-limit: 10
- # Maintain dependencies for pip
+ # Maintain dependencies for documentation
- package-ecosystem: "pip"
- directory: "/"
+ directory: "/docs/"
schedule:
interval: "daily"
assignees:
- "LeMyst"
+ open-pull-requests-limit: 10
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 00000000..9da2e983
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+ configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+ - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+ version: "3.8"
+ install:
+ - method: pip
+ path: .
+ extra_requirements:
+ - docs
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 00000000..ba501f6f
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+SOURCEDIR = source
+BUILDDIR = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..216bff58
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,5 @@
+# Sphinx-apidoc
+
+```shell
+sphinx-apidoc.exe -e -f -o docs\source .\wikibaseintegrator\ -t docs\source\_templates
+```
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 00000000..6247f7e2
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 00000000..a7805ab3
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,6 @@
+Sphinx~=4.2.0
+readthedocs-sphinx-ext~=2.1.4
+sphinx-rtd-theme~=1.0.0
+git+https://github.com/LeMyst/sphinx-github-changelog.git@1.0.8-Sphinx-4.2.0#egg=sphinx_github_changelog
+m2r2~=0.3.1
+sphinx-autodoc-typehints~=1.12.0
diff --git a/docs/source/_templates/module.rst_t b/docs/source/_templates/module.rst_t
new file mode 100644
index 00000000..d886dcfb
--- /dev/null
+++ b/docs/source/_templates/module.rst_t
@@ -0,0 +1,9 @@
+{%- if show_headings %}
+{{- [basename] | join(' ') | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+ :{{ option }}:
+{%- endfor %}
+
diff --git a/docs/source/_templates/package.rst_t b/docs/source/_templates/package.rst_t
new file mode 100644
index 00000000..2eb85377
--- /dev/null
+++ b/docs/source/_templates/package.rst_t
@@ -0,0 +1,48 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+ :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+ :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+ {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{{- [pkgname] | join(" ") | e | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if subpackages %}
+Subpackages
+-----------
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{%- if subpackages %}
+Submodules
+----------
+{%- endif %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
diff --git a/docs/source/_templates/toc.rst_t b/docs/source/_templates/toc.rst_t
new file mode 100644
index 00000000..846c6b16
--- /dev/null
+++ b/docs/source/_templates/toc.rst_t
@@ -0,0 +1,7 @@
+{{ header | heading }}
+
+.. toctree::
+ :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+ {{ docname }}
+{%- endfor %}
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
new file mode 100644
index 00000000..85fb4e01
--- /dev/null
+++ b/docs/source/changelog.rst
@@ -0,0 +1,9 @@
+.. _changelog:
+
+Changelog
+*********
+
+.. changelog::
+ :changelog-url: https://wikibaseintegrator.readthedocs.io/en/stable/#changelog
+ :github: https://github.com/LeMyst/WikibaseIntegrator/releases/
+ :pypi: https://pypi.org/project/wikibaseintegrator/
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 00000000..050b7ed8
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,120 @@
+# -*- coding: utf-8 -*-
+#
+# 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
+
+from datetime import datetime
+
+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',
+ 'sphinx.ext.mathjax',
+ 'sphinx.ext.viewcode',
+ 'sphinx_rtd_theme',
+ 'sphinx_github_changelog',
+ 'm2r2',
+ 'sphinx_autodoc_typehints']
+
+# Provide a GitHub API token:
+# Pass the SPHINX_GITHUB_CHANGELOG_TOKEN environment variable to your build
+# OR
+# sphinx_github_changelog_token = ""
+
+# 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': 'restructuredtext'}
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'WikibaseIntegrator'
+copyright = u'%d, LeMyst' % datetime.now().year
+author = u'LeMyst and WikibaseIntegrator 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 = u'0.12.0'
+# The full version, including alpha/beta/rc tags.
+release = u'0.12.0'
+
+# 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 = []
+
+# 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
+
+autodoc_typehints = 'both'
+autodoc_default_options = {
+ 'special-members': '__init__',
+ 'members': True,
+ 'undoc-members': True,
+ 'inherited-members': True,
+ 'show-inheritance': True,
+ 'exclude-members': 'subclasses'
+}
+
+# -- 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'
+
+html_theme_options = {
+ 'style_external_links': False,
+ # Toc options
+ 'collapse_navigation': False
+}
+
+html_context = {
+ 'display_github': True,
+ 'github_user': 'LeMyst',
+ 'github_repo': 'WikibaseIntegrator',
+ 'github_version': 'master',
+ "conf_py_path": "/docs/"
+}
+
+
+def skip(app, what, name, obj, would_skip, options):
+ if name == "__init__":
+ return False
+ if name == "sparql_query":
+ return True
+ return would_skip
+
+
+def setup(app):
+ app.connect("autodoc-skip-member", skip)
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 00000000..5774be85
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,33 @@
+.. _index:
+
+WikibaseIntegrator
+==================
+
+.. toctree::
+ :maxdepth: 5
+
+ wikibaseintegrator
+
+..
+ README
+ ======
+
+ .. mdinclude:: ../../README.md
+
+
+Changelog
+=========
+
+.. toctree::
+ :maxdepth: 5
+ :caption: Miscellaneous
+
+ changelog
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
new file mode 100644
index 00000000..c8c8f23d
--- /dev/null
+++ b/docs/source/modules.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator
+==================
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator
\ No newline at end of file
diff --git a/docs/source/wikibaseintegrator.datatypes.basedatatype.rst b/docs/source/wikibaseintegrator.datatypes.basedatatype.rst
new file mode 100644
index 00000000..db7f462f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.basedatatype.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.basedatatype
+=========================================
+
+.. automodule:: wikibaseintegrator.datatypes.basedatatype
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.commonsmedia.rst b/docs/source/wikibaseintegrator.datatypes.commonsmedia.rst
new file mode 100644
index 00000000..b210ec2a
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.commonsmedia.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.commonsmedia
+=========================================
+
+.. automodule:: wikibaseintegrator.datatypes.commonsmedia
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.externalid.rst b/docs/source/wikibaseintegrator.datatypes.externalid.rst
new file mode 100644
index 00000000..0c5ffb0d
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.externalid.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.externalid
+=======================================
+
+.. automodule:: wikibaseintegrator.datatypes.externalid
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.extra.edtf.rst b/docs/source/wikibaseintegrator.datatypes.extra.edtf.rst
new file mode 100644
index 00000000..82db2eb9
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.extra.edtf.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.extra.edtf
+=======================================
+
+.. automodule:: wikibaseintegrator.datatypes.extra.edtf
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.extra.localmedia.rst b/docs/source/wikibaseintegrator.datatypes.extra.localmedia.rst
new file mode 100644
index 00000000..b8a40e8c
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.extra.localmedia.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.extra.localmedia
+=============================================
+
+.. automodule:: wikibaseintegrator.datatypes.extra.localmedia
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.extra.rst b/docs/source/wikibaseintegrator.datatypes.extra.rst
new file mode 100644
index 00000000..13426ded
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.extra.rst
@@ -0,0 +1,9 @@
+wikibaseintegrator.datatypes.extra
+==================================
+
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.datatypes.extra.edtf
+ wikibaseintegrator.datatypes.extra.localmedia
diff --git a/docs/source/wikibaseintegrator.datatypes.form.rst b/docs/source/wikibaseintegrator.datatypes.form.rst
new file mode 100644
index 00000000..56ee30d2
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.form.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.form
+=================================
+
+.. automodule:: wikibaseintegrator.datatypes.form
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.geoshape.rst b/docs/source/wikibaseintegrator.datatypes.geoshape.rst
new file mode 100644
index 00000000..dbf46e2b
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.geoshape.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.geoshape
+=====================================
+
+.. automodule:: wikibaseintegrator.datatypes.geoshape
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.globecoordinate.rst b/docs/source/wikibaseintegrator.datatypes.globecoordinate.rst
new file mode 100644
index 00000000..4b5f8df8
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.globecoordinate.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.globecoordinate
+============================================
+
+.. automodule:: wikibaseintegrator.datatypes.globecoordinate
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.item.rst b/docs/source/wikibaseintegrator.datatypes.item.rst
new file mode 100644
index 00000000..8113deb9
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.item.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.item
+=================================
+
+.. automodule:: wikibaseintegrator.datatypes.item
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.lexeme.rst b/docs/source/wikibaseintegrator.datatypes.lexeme.rst
new file mode 100644
index 00000000..8f9141ee
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.lexeme.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.lexeme
+===================================
+
+.. automodule:: wikibaseintegrator.datatypes.lexeme
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.math.rst b/docs/source/wikibaseintegrator.datatypes.math.rst
new file mode 100644
index 00000000..10ff4221
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.math.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.math
+=================================
+
+.. automodule:: wikibaseintegrator.datatypes.math
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.monolingualtext.rst b/docs/source/wikibaseintegrator.datatypes.monolingualtext.rst
new file mode 100644
index 00000000..95257695
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.monolingualtext.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.monolingualtext
+============================================
+
+.. automodule:: wikibaseintegrator.datatypes.monolingualtext
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.musicalnotation.rst b/docs/source/wikibaseintegrator.datatypes.musicalnotation.rst
new file mode 100644
index 00000000..c941619f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.musicalnotation.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.musicalnotation
+============================================
+
+.. automodule:: wikibaseintegrator.datatypes.musicalnotation
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.property.rst b/docs/source/wikibaseintegrator.datatypes.property.rst
new file mode 100644
index 00000000..f6845640
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.property.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.property
+=====================================
+
+.. automodule:: wikibaseintegrator.datatypes.property
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.quantity.rst b/docs/source/wikibaseintegrator.datatypes.quantity.rst
new file mode 100644
index 00000000..5d9ecc3f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.quantity.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.quantity
+=====================================
+
+.. automodule:: wikibaseintegrator.datatypes.quantity
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.rst b/docs/source/wikibaseintegrator.datatypes.rst
new file mode 100644
index 00000000..fb450673
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.rst
@@ -0,0 +1,35 @@
+wikibaseintegrator.datatypes
+============================
+
+Subpackages
+-----------
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.datatypes.extra
+
+Submodules
+----------
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.datatypes.basedatatype
+ wikibaseintegrator.datatypes.commonsmedia
+ wikibaseintegrator.datatypes.externalid
+ wikibaseintegrator.datatypes.form
+ wikibaseintegrator.datatypes.geoshape
+ wikibaseintegrator.datatypes.globecoordinate
+ wikibaseintegrator.datatypes.item
+ wikibaseintegrator.datatypes.lexeme
+ wikibaseintegrator.datatypes.math
+ wikibaseintegrator.datatypes.monolingualtext
+ wikibaseintegrator.datatypes.musicalnotation
+ wikibaseintegrator.datatypes.property
+ wikibaseintegrator.datatypes.quantity
+ wikibaseintegrator.datatypes.sense
+ wikibaseintegrator.datatypes.string
+ wikibaseintegrator.datatypes.tabulardata
+ wikibaseintegrator.datatypes.time
+ wikibaseintegrator.datatypes.url
diff --git a/docs/source/wikibaseintegrator.datatypes.sense.rst b/docs/source/wikibaseintegrator.datatypes.sense.rst
new file mode 100644
index 00000000..601d91a7
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.sense.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.sense
+==================================
+
+.. automodule:: wikibaseintegrator.datatypes.sense
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.string.rst b/docs/source/wikibaseintegrator.datatypes.string.rst
new file mode 100644
index 00000000..d5feba7b
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.string.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.string
+===================================
+
+.. automodule:: wikibaseintegrator.datatypes.string
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.tabulardata.rst b/docs/source/wikibaseintegrator.datatypes.tabulardata.rst
new file mode 100644
index 00000000..e363421d
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.tabulardata.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.tabulardata
+========================================
+
+.. automodule:: wikibaseintegrator.datatypes.tabulardata
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.time.rst b/docs/source/wikibaseintegrator.datatypes.time.rst
new file mode 100644
index 00000000..5a26f7fc
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.time.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.time
+=================================
+
+.. automodule:: wikibaseintegrator.datatypes.time
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.url.rst b/docs/source/wikibaseintegrator.datatypes.url.rst
new file mode 100644
index 00000000..feda6427
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.url.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.url
+================================
+
+.. automodule:: wikibaseintegrator.datatypes.url
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.baseentity.rst b/docs/source/wikibaseintegrator.entities.baseentity.rst
new file mode 100644
index 00000000..03f52769
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.baseentity.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.baseentity
+======================================
+
+.. automodule:: wikibaseintegrator.entities.baseentity
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.item.rst b/docs/source/wikibaseintegrator.entities.item.rst
new file mode 100644
index 00000000..c8943e29
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.item.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.item
+================================
+
+.. automodule:: wikibaseintegrator.entities.item
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.lexeme.rst b/docs/source/wikibaseintegrator.entities.lexeme.rst
new file mode 100644
index 00000000..c4d1e683
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.lexeme.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.lexeme
+==================================
+
+.. automodule:: wikibaseintegrator.entities.lexeme
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.mediainfo.rst b/docs/source/wikibaseintegrator.entities.mediainfo.rst
new file mode 100644
index 00000000..a3283d0f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.mediainfo.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.mediainfo
+=====================================
+
+.. automodule:: wikibaseintegrator.entities.mediainfo
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.property.rst b/docs/source/wikibaseintegrator.entities.property.rst
new file mode 100644
index 00000000..183603b4
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.property.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.property
+====================================
+
+.. automodule:: wikibaseintegrator.entities.property
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.rst b/docs/source/wikibaseintegrator.entities.rst
new file mode 100644
index 00000000..905ae27b
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.rst
@@ -0,0 +1,12 @@
+wikibaseintegrator.entities
+===========================
+
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.entities.baseentity
+ wikibaseintegrator.entities.item
+ wikibaseintegrator.entities.lexeme
+ wikibaseintegrator.entities.mediainfo
+ wikibaseintegrator.entities.property
diff --git a/docs/source/wikibaseintegrator.models.aliases.rst b/docs/source/wikibaseintegrator.models.aliases.rst
new file mode 100644
index 00000000..57bb0c0f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.aliases.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.aliases
+=================================
+
+.. automodule:: wikibaseintegrator.models.aliases
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.basemodel.rst b/docs/source/wikibaseintegrator.models.basemodel.rst
new file mode 100644
index 00000000..697e03cd
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.basemodel.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.basemodel
+===================================
+
+.. automodule:: wikibaseintegrator.models.basemodel
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.claims.rst b/docs/source/wikibaseintegrator.models.claims.rst
new file mode 100644
index 00000000..16385a5b
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.claims.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.claims
+================================
+
+.. automodule:: wikibaseintegrator.models.claims
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.descriptions.rst b/docs/source/wikibaseintegrator.models.descriptions.rst
new file mode 100644
index 00000000..40822474
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.descriptions.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.descriptions
+======================================
+
+.. automodule:: wikibaseintegrator.models.descriptions
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.forms.rst b/docs/source/wikibaseintegrator.models.forms.rst
new file mode 100644
index 00000000..c21b0da0
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.forms.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.forms
+===============================
+
+.. automodule:: wikibaseintegrator.models.forms
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.labels.rst b/docs/source/wikibaseintegrator.models.labels.rst
new file mode 100644
index 00000000..e5532e78
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.labels.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.labels
+================================
+
+.. automodule:: wikibaseintegrator.models.labels
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.language_values.rst b/docs/source/wikibaseintegrator.models.language_values.rst
new file mode 100644
index 00000000..ae17c258
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.language_values.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.language\_values
+==========================================
+
+.. automodule:: wikibaseintegrator.models.language_values
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.lemmas.rst b/docs/source/wikibaseintegrator.models.lemmas.rst
new file mode 100644
index 00000000..c39994e0
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.lemmas.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.lemmas
+================================
+
+.. automodule:: wikibaseintegrator.models.lemmas
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.qualifiers.rst b/docs/source/wikibaseintegrator.models.qualifiers.rst
new file mode 100644
index 00000000..eea12fb5
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.qualifiers.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.qualifiers
+====================================
+
+.. automodule:: wikibaseintegrator.models.qualifiers
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.references.rst b/docs/source/wikibaseintegrator.models.references.rst
new file mode 100644
index 00000000..138e7212
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.references.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.references
+====================================
+
+.. automodule:: wikibaseintegrator.models.references
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.rst b/docs/source/wikibaseintegrator.models.rst
new file mode 100644
index 00000000..833ef137
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.rst
@@ -0,0 +1,20 @@
+wikibaseintegrator.models
+=========================
+
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.models.aliases
+ wikibaseintegrator.models.basemodel
+ wikibaseintegrator.models.claims
+ wikibaseintegrator.models.descriptions
+ wikibaseintegrator.models.forms
+ wikibaseintegrator.models.labels
+ wikibaseintegrator.models.language_values
+ wikibaseintegrator.models.lemmas
+ wikibaseintegrator.models.qualifiers
+ wikibaseintegrator.models.references
+ wikibaseintegrator.models.senses
+ wikibaseintegrator.models.sitelinks
+ wikibaseintegrator.models.snaks
diff --git a/docs/source/wikibaseintegrator.models.senses.rst b/docs/source/wikibaseintegrator.models.senses.rst
new file mode 100644
index 00000000..6e0c99ca
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.senses.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.senses
+================================
+
+.. automodule:: wikibaseintegrator.models.senses
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.sitelinks.rst b/docs/source/wikibaseintegrator.models.sitelinks.rst
new file mode 100644
index 00000000..b7ac4ab0
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.sitelinks.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.sitelinks
+===================================
+
+.. automodule:: wikibaseintegrator.models.sitelinks
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.snaks.rst b/docs/source/wikibaseintegrator.models.snaks.rst
new file mode 100644
index 00000000..eece442f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.snaks.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.snaks
+===============================
+
+.. automodule:: wikibaseintegrator.models.snaks
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.rst b/docs/source/wikibaseintegrator.rst
new file mode 100644
index 00000000..802df089
--- /dev/null
+++ b/docs/source/wikibaseintegrator.rst
@@ -0,0 +1,27 @@
+wikibaseintegrator
+==================
+
+Subpackages
+-----------
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.datatypes
+ wikibaseintegrator.entities
+ wikibaseintegrator.models
+
+Submodules
+----------
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.wbi_backoff
+ wikibaseintegrator.wbi_config
+ wikibaseintegrator.wbi_enums
+ wikibaseintegrator.wbi_exceptions
+ wikibaseintegrator.wbi_fastrun
+ wikibaseintegrator.wbi_helpers
+ wikibaseintegrator.wbi_login
+ wikibaseintegrator.wikibaseintegrator
diff --git a/docs/source/wikibaseintegrator.wbi_backoff.rst b/docs/source/wikibaseintegrator.wbi_backoff.rst
new file mode 100644
index 00000000..fe4665a4
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_backoff.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_backoff
+===============================
+
+.. automodule:: wikibaseintegrator.wbi_backoff
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_config.rst b/docs/source/wikibaseintegrator.wbi_config.rst
new file mode 100644
index 00000000..95c816c3
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_config.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_config
+==============================
+
+.. automodule:: wikibaseintegrator.wbi_config
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_enums.rst b/docs/source/wikibaseintegrator.wbi_enums.rst
new file mode 100644
index 00000000..a2161406
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_enums.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_enums
+=============================
+
+.. automodule:: wikibaseintegrator.wbi_enums
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_exceptions.rst b/docs/source/wikibaseintegrator.wbi_exceptions.rst
new file mode 100644
index 00000000..a9175027
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_exceptions.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_exceptions
+==================================
+
+.. automodule:: wikibaseintegrator.wbi_exceptions
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_fastrun.rst b/docs/source/wikibaseintegrator.wbi_fastrun.rst
new file mode 100644
index 00000000..15e436ed
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_fastrun.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_fastrun
+===============================
+
+.. automodule:: wikibaseintegrator.wbi_fastrun
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_helpers.rst b/docs/source/wikibaseintegrator.wbi_helpers.rst
new file mode 100644
index 00000000..4a36b544
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_helpers.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_helpers
+===============================
+
+.. automodule:: wikibaseintegrator.wbi_helpers
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_login.rst b/docs/source/wikibaseintegrator.wbi_login.rst
new file mode 100644
index 00000000..f287a9f5
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_login.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_login
+=============================
+
+.. automodule:: wikibaseintegrator.wbi_login
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wikibaseintegrator.rst b/docs/source/wikibaseintegrator.wikibaseintegrator.rst
new file mode 100644
index 00000000..cee861b9
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wikibaseintegrator.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wikibaseintegrator
+=====================================
+
+.. automodule:: wikibaseintegrator.wikibaseintegrator
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/pyproject.toml b/pyproject.toml
index 8b387b68..80143fed 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -21,7 +21,6 @@ extension-pkg-allow-list = [
max-line-length = 180
disable = [
"fixme",
- "missing-docstring",
"redefined-builtin",
"invalid-name", # To remove later
"too-few-public-methods",
diff --git a/setup.cfg b/setup.cfg
index 9a8c5cdd..81e586cc 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -45,5 +45,12 @@ dev =
pylint
pylint-exit
mypy
+docs =
+ Sphinx~=4.2.0
+ readthedocs-sphinx-ext~=2.1.4
+ sphinx-rtd-theme~=1.0.0
+ sphinx_github_changelog @ git+https://github.com/LeMyst/sphinx-github-changelog.git@1.0.8-Sphinx-4.2.0#egg=sphinx_github_changelog
+ m2r2~=0.3.1
+ sphinx-autodoc-typehints~=1.12.0
coverage =
pytest-cov
diff --git a/setup.py b/setup.py
index abedd3fd..fe65a962 100644
--- a/setup.py
+++ b/setup.py
@@ -18,6 +18,14 @@
"pylint-exit",
"mypy"
],
+ "docs": [
+ "Sphinx ~= 4.2.0",
+ "readthedocs-sphinx-ext ~= 2.1.4",
+ "sphinx-rtd-theme ~= 1.0.0",
+ "sphinx_github_changelog @ git+https://github.com/LeMyst/sphinx-github-changelog.git@1.0.8-Sphinx-4.2.0#egg=sphinx_github_changelog",
+ "m2r2 ~= 0.3.1",
+ "sphinx-autodoc-typehints ~= 1.12.0"
+ ],
"coverage": ["pytest-cov"],
},
)
diff --git a/wikibaseintegrator/__init__.py b/wikibaseintegrator/__init__.py
index d3f39e8d..7e2e06e9 100644
--- a/wikibaseintegrator/__init__.py
+++ b/wikibaseintegrator/__init__.py
@@ -1,3 +1,20 @@
+"""
+WikibaseIntegrator Library
+~~~~~~~~~~~~~~~~~~~~~
+
+WikibaseIntegrator is a Wikibase library, written in Python, for human beings.
+Basic read usage:
+
+ >>> from wikibaseintegrator import WikibaseIntegrator
+ >>> from wikibaseintegrator.wbi_config import config
+ >>> config['USER_AGENT'] = 'Item Get Notebook'
+ >>> wbi = WikibaseIntegrator()
+ >>> q42 = wbi.item.get('Q42')
+ >>> q42.labels.get('en').value
+ 'Douglas Adams'
+
+Full documentation is available at .
+"""
import pkg_resources
from .wikibaseintegrator import WikibaseIntegrator
diff --git a/wikibaseintegrator/datatypes/geoshape.py b/wikibaseintegrator/datatypes/geoshape.py
index 3e013387..7a7210bc 100644
--- a/wikibaseintegrator/datatypes/geoshape.py
+++ b/wikibaseintegrator/datatypes/geoshape.py
@@ -21,23 +21,19 @@ def __init__(self, value: str = None, **kwargs: Any):
Constructor, calls the superclass BaseDataType
:param value: The GeoShape map file name in Wikimedia Commons to be linked
- :type value: str or None
- :param prop_nr: The item ID for this claim
- :type prop_nr: str with a 'P' prefix followed by digits
- :param snaktype: The snak type, either 'value', 'somevalue' or 'novalue'
- :type snaktype: str
- :param references: List with reference objects
- :type references: A data type with subclass of BaseDataType
- :param qualifiers: List with qualifier objects
- :type qualifiers: A data type with subclass of BaseDataType
- :param rank: rank of a snak with value 'preferred', 'normal' or 'deprecated'
- :type rank: str
+ :param kwargs:
:Keyword Arguments:
- * *extra* (``list``) --
- Extra stuff
- * *supplement* (``dict``) --
- Additional content
+ * *prop_nr* (``str``) --
+ The item ID for this claim
+ * *snaktype* (``str``) --
+ The snak type, either 'value', 'somevalue' or 'novalue'
+ * *references* (``References`` or list of ``Claim``) --
+ List with reference objects
+ * *qualifiers* (``Qualifiers``) --
+ List with qualifier objects
+ * *rank* (``WikibaseRank``) --
+ The snak type, either 'value', 'somevalue' or 'novalue'
"""
super().__init__(**kwargs)
diff --git a/wikibaseintegrator/entities/baseentity.py b/wikibaseintegrator/entities/baseentity.py
index c8f77f2e..9bfa1375 100644
--- a/wikibaseintegrator/entities/baseentity.py
+++ b/wikibaseintegrator/entities/baseentity.py
@@ -49,6 +49,11 @@ def add_claims(self, claims: Union[Claim, list], action_if_exists: ActionIfExist
return self
def get_json(self) -> Dict[str, Union[str, Dict[str, list]]]:
+ """
+ To get the dict equivalent of the JSON representation of the entity.
+
+ :return:
+ """
json_data: Dict = {
'type': self.type,
'claims': self.claims.get_json()
@@ -77,7 +82,7 @@ def from_json(self, json_data: Dict[str, Any]) -> BaseEntity:
# noinspection PyMethodMayBeStatic
def _get(self, entity_id: str, **kwargs: Any) -> Dict: # pylint: disable=no-self-use
"""
- retrieve an item in json representation from the Wikibase instance
+ Retrieve an entity in json representation from the Wikibase instance
:return: python complex dictionary representation of a json
"""
diff --git a/wikibaseintegrator/entities/item.py b/wikibaseintegrator/entities/item.py
index 09317b5a..121eaaf9 100644
--- a/wikibaseintegrator/entities/item.py
+++ b/wikibaseintegrator/entities/item.py
@@ -38,6 +38,13 @@ def new(self, **kwargs: Any) -> Item:
return Item(api=self.api, **kwargs)
def get(self, entity_id: Union[str, int], **kwargs: Any) -> Item:
+ """
+ Request the Mediawiki API to get data for the entity specified in argument.
+
+ :param entity_id: The entity_id of the Item entity you want. Must start with a 'Q'.
+ :param kwargs:
+ :return: an Item instance
+ """
if isinstance(entity_id, str):
pattern = re.compile(r'^Q?([0-9]+)$')
matches = pattern.match(entity_id)
@@ -55,6 +62,11 @@ def get(self, entity_id: Union[str, int], **kwargs: Any) -> Item:
return Item(api=self.api).from_json(json_data=json_data['entities'][entity_id])
def get_json(self) -> Dict[str, Union[str, Dict]]:
+ """
+ To get the dict equivalent of the JSON representation of the Item.
+
+ :return: A dict representation of the Item.
+ """
return {
'labels': self.labels.get_json(),
'descriptions': self.descriptions.get_json(),
diff --git a/wikibaseintegrator/models/claims.py b/wikibaseintegrator/models/claims.py
index 12366851..54f7bf7b 100644
--- a/wikibaseintegrator/models/claims.py
+++ b/wikibaseintegrator/models/claims.py
@@ -123,6 +123,12 @@ class Claim(BaseModel):
DTYPE = 'claim'
def __init__(self, qualifiers: Qualifiers = None, rank: WikibaseRank = None, references: Union[References, List[Union[Claim, List[Claim]]]] = None) -> None:
+ """
+
+ :param qualifiers:
+ :param rank:
+ :param references: A References object, a list of Claim object or a list of list of Claim object
+ """
self.mainsnak = Snak(datatype=self.DTYPE)
self.type = 'statement'
self.qualifiers = qualifiers or Qualifiers()
@@ -225,6 +231,10 @@ def remove(self, remove=True) -> None:
self.removed = remove
def from_json(self, json_data: Dict[str, Any]) -> Claim:
+ """
+
+ :param json_data: a JSON representation of a Claim
+ """
self.mainsnak = Snak().from_json(json_data['mainsnak'])
self.type = str(json_data['type'])
if 'qualifiers' in json_data:
diff --git a/wikibaseintegrator/models/language_values.py b/wikibaseintegrator/models/language_values.py
index aa2ba814..182fea92 100644
--- a/wikibaseintegrator/models/language_values.py
+++ b/wikibaseintegrator/models/language_values.py
@@ -12,7 +12,10 @@ def __init__(self):
self.values = {}
@property
- def values(self):
+ def values(self) -> Dict[str, LanguageValue]:
+ """
+ A dict of LanguageValue with the language as key.
+ """
return self.__values
@values.setter
@@ -20,6 +23,12 @@ def values(self, value):
self.__values = value
def add(self, language_value: LanguageValue) -> LanguageValues:
+ """
+ Add a LanguageValue object to the list
+
+ :param language_value: A LanguageValue object
+ :return: The current LanguageValues object
+ """
assert isinstance(language_value, LanguageValue)
if language_value.value:
@@ -28,6 +37,12 @@ def add(self, language_value: LanguageValue) -> LanguageValues:
return self
def get(self, language: str = None) -> Optional[LanguageValue]:
+ """
+ Get a LanguageValue object with the specified language. Use the default language in wbi_config if none specified.
+
+ :param language: The requested language.
+ :return: The related LanguageValue object or None if none found.
+ """
language = str(language or config['DEFAULT_LANGUAGE'])
if language in self.values:
return self.values[language]
@@ -35,12 +50,21 @@ def get(self, language: str = None) -> Optional[LanguageValue]:
return None
def set(self, language: str = None, value: str = None, action_if_exists: ActionIfExists = ActionIfExists.REPLACE) -> Optional[LanguageValue]:
+ """
+ Create or update the specified language with the valued passed in arguments.
+
+ :param language: The desired language.
+ :param value: The desired value of the LanguageValue object. Use None to delete an existing LanguageValue object from the list.
+ :param action_if_exists: The action if the LanguageValue object is already defined. Can be ActionIfExists.REPLACE (default) or ActionIfExists.KEEP.
+ :return: The created or updated LanguageValue. None if there's no LanguageValue object with this language.
+ """
language = str(language or config['DEFAULT_LANGUAGE'])
assert action_if_exists in [ActionIfExists.REPLACE, ActionIfExists.KEEP]
# Remove value if None
- if value is None and language in self.values:
- self.values[language].remove()
+ if value is None:
+ if language in self.values:
+ self.values[language].remove()
return None
if action_if_exists == ActionIfExists.REPLACE or self.get(language=language) is None:
@@ -51,12 +75,23 @@ def set(self, language: str = None, value: str = None, action_if_exists: ActionI
return self.get(language=language)
def from_json(self, json_data: Dict[str, Dict]) -> LanguageValues:
+ """
+ Create a new LanguageValues object from a JSON/dict object.
+
+ :param json_data: A dict object who use the same format as Wikibase.
+ :return: The newly created or updated object.
+ """
for language_value in json_data:
self.add(language_value=LanguageValue(language=json_data[language_value]['language']).from_json(json_data=json_data[language_value]))
return self
def get_json(self) -> Dict[str, Dict]:
+ """
+ Get a formated dict who respect the Wikibase format.
+
+ :return: A dict using Wikibase format.
+ """
json_data: Dict[str, Dict] = {}
for language, language_value in self.values.items():
json_data[language] = language_value.get_json()
@@ -74,11 +109,11 @@ def __init__(self, language: str, value: str = None):
self.removed = False
@property
- def language(self):
+ def language(self) -> str:
return self.__language
@language.setter
- def language(self, value):
+ def language(self, value: Optional[str]):
if value is None:
raise ValueError("language can't be None")
@@ -91,19 +126,23 @@ def language(self, value):
self.__language = value
@property
- def value(self):
+ def value(self) -> Optional[str]:
+ """
+ The value of the LanguageValue instance.
+ :return: A string with the value of the LanguageValue instance.
+ """
return self.__value
@value.setter
- def value(self, value):
+ def value(self, value: Optional[str]):
self.__value = value
@property
- def removed(self):
+ def removed(self) -> bool:
return self.__removed
@removed.setter
- def removed(self, value):
+ def removed(self, value: bool):
self.__removed = value
def remove(self) -> LanguageValue:
@@ -117,7 +156,7 @@ def from_json(self, json_data: Dict[str, str]) -> LanguageValue:
return self
- def get_json(self) -> Dict[str, str]:
+ def get_json(self) -> Dict[str, Optional[str]]:
json_data = {
'language': self.language,
'value': self.value
diff --git a/wikibaseintegrator/wbi_backoff.py b/wikibaseintegrator/wbi_backoff.py
index 93b15b9f..edbbf0f1 100644
--- a/wikibaseintegrator/wbi_backoff.py
+++ b/wikibaseintegrator/wbi_backoff.py
@@ -1,3 +1,6 @@
+"""
+WikibaseIntegrator implementation of backoff python library.
+"""
import sys
from functools import partial
from json import JSONDecodeError
@@ -15,12 +18,10 @@ def wbi_backoff_backoff_hdlr(details):
print("Backing off {wait:0.1f} seconds afters {tries} tries calling function with args {args} and kwargs {kwargs}".format(**details)) # pylint: disable=consider-using-f-string
-def wbi_backoff_check_json_decode_error(e):
+def wbi_backoff_check_json_decode_error(e) -> bool:
"""
Check if the error message is "Expecting value: line 1 column 1 (char 0)"
if not, its a real error and we shouldn't retry
- :param e:
- :return:
"""
return isinstance(e, JSONDecodeError) and str(e) != "Expecting value: line 1 column 1 (char 0)"
diff --git a/wikibaseintegrator/wbi_fastrun.py b/wikibaseintegrator/wbi_fastrun.py
index 5cd3cf77..de62004f 100644
--- a/wikibaseintegrator/wbi_fastrun.py
+++ b/wikibaseintegrator/wbi_fastrun.py
@@ -110,6 +110,14 @@ def reconstruct_statements(self, qid: str) -> List[BaseDataType]:
return reconstructed_statements
def get_item(self, claims: Union[list, Claims], cqid: str = None) -> Optional[str]:
+ """
+ Load an item from the SPARQL endpoint.
+
+ :param claims:
+ :param cqid:
+ :return: the claim id
+ :exception: if there is more than one claim
+ """
match_sets = []
for claim in claims:
# skip to next if statement has no value or no data type defined, e.g. for deletion objects
@@ -165,6 +173,14 @@ def get_item(self, claims: Union[list, Claims], cqid: str = None) -> Optional[st
return matching_qids.pop()
def write_required(self, data: List[BaseDataType], action_if_exists: ActionIfExists = ActionIfExists.REPLACE, cqid: str = None) -> bool:
+ """
+ Check if a write is required
+
+ :param data:
+ :param action_if_exists:
+ :param cqid:
+ :return: Return True if the write is required
+ """
del_props = set()
data_props = set()
append_props = []
@@ -260,6 +276,7 @@ def write_required(self, data: List[BaseDataType], action_if_exists: ActionIfExi
def init_language_data(self, lang: str, lang_data_type: str) -> None:
"""
Initialize language data store
+
:param lang: language code
:param lang_data_type: 'label', 'description' or 'aliases'
:return: None
diff --git a/wikibaseintegrator/wbi_helpers.py b/wikibaseintegrator/wbi_helpers.py
index c6882cf6..62386602 100644
--- a/wikibaseintegrator/wbi_helpers.py
+++ b/wikibaseintegrator/wbi_helpers.py
@@ -32,21 +32,21 @@ class BColors:
UNDERLINE = '\033[4m'
-# Session used for anonymous requests
+# Session used for all anonymous requests
default_session = requests.Session()
def mediawiki_api_call(method: str, mediawiki_api_url: str = None, session: Session = None, max_retries: int = 100, retry_after: int = 60, **kwargs: Any) -> Dict:
"""
+ A function to call the Mediawiki API.
+
:param method: 'GET' or 'POST'
:param mediawiki_api_url:
:param session: If a session is passed, it will be used. Otherwise a new requests session is created
:param max_retries: If api request fails due to rate limiting, maxlag, or readonly mode, retry up to `max_retries` times
- :type max_retries: int
:param retry_after: Number of seconds to wait before retrying request (see max_retries)
- :type retry_after: int
- :param kwargs: Passed to requests.request
- :return:
+ :param kwargs: Any additional keyword arguments to pass to requests.request
+ :return: The data returned by the API as a dictionary
"""
mediawiki_api_url = str(mediawiki_api_url or config['MEDIAWIKI_API_URL'])
@@ -124,6 +124,21 @@ def mediawiki_api_call(method: str, mediawiki_api_url: str = None, session: Sess
def mediawiki_api_call_helper(data: Dict[str, Any] = None, login: Login = None, mediawiki_api_url: str = None, user_agent: str = None, allow_anonymous: bool = False,
max_retries: int = 1000, retry_after: int = 60, maxlag: int = 5, is_bot: bool = False, **kwargs: Any) -> Dict:
+ """
+ A simplified function to call the Mediawiki API
+
+ :param data: A dictionary containing the JSON data to send to the API
+ :param login: A wbi_login instance
+ :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata)
+ :param user_agent: The user agent (Recommended for Wikimedia Foundation instances)
+ :param allow_anonymous: Allow an unidentified edit to the Mediawiki API (default False)
+ :param max_retries: The maximum number of retries
+ :param retry_after: The tiemout between each retry
+ :param maxlag: If appliable, the maximum lag allowed for the replication (An lower number reduce the load on the replicated database)
+ :param is_bot: Flag the edit as a bot
+ :param kwargs: Any additional keyword arguments to pass to requests.request
+ :return: The data returned by the API as a dictionary
+ """
mediawiki_api_url = str(mediawiki_api_url or config['MEDIAWIKI_API_URL'])
user_agent = user_agent or (str(config['USER_AGENT']) if config['USER_AGENT'] is not None else None)
@@ -177,6 +192,7 @@ def mediawiki_api_call_helper(data: Dict[str, Any] = None, login: Login = None,
def execute_sparql_query(query: str, prefix: str = None, endpoint: str = None, user_agent: str = None, max_retries: int = 1000, retry_after: int = 60) -> Optional[Dict[str, dict]]:
"""
Static method which can be used to execute any SPARQL query
+
:param prefix: The URI prefixes required for an endpoint, default is the Wikidata specific prefixes
:param query: The actual SPARQL query string
:param endpoint: The URL string for the SPARQL endpoint. Default is the URL for the Wikidata SPARQL endpoint
@@ -235,12 +251,13 @@ def execute_sparql_query(query: str, prefix: str = None, endpoint: str = None, u
return None
-def merge_items(from_id: str, to_id: str, ignore_conflicts: List[str] = None, is_bot: bool = False, **kwargs: Any) -> Dict:
+def merge_items(from_id: str, to_id: str, login: Login = None, ignore_conflicts: List[str] = None, is_bot: bool = False, **kwargs: Any) -> Dict:
"""
A static method to merge two items
:param from_id: The ID to merge from. This parameter is required.
:param to_id: The ID to merge to. This parameter is required.
+ :param login: A wbi_login.Login instance
:param ignore_conflicts: List of elements of the item to ignore conflicts for. Can only contain values of "description", "sitelink" and "statement"
:param is_bot: Mark this edit as bot.
"""
@@ -258,12 +275,12 @@ def merge_items(from_id: str, to_id: str, ignore_conflicts: List[str] = None, is
if is_bot:
params.update({'bot': ''})
- return mediawiki_api_call_helper(data=params, **kwargs)
+ return mediawiki_api_call_helper(data=params, login=login, **kwargs)
def merge_lexemes(source: str, target: str, summary: str = None, is_bot: bool = False, **kwargs: Any) -> Dict:
"""
- A static method to merge two items
+ A static method to merge two lexemes
:param source: The ID to merge from. This parameter is required.
:param target: The ID to merge to. This parameter is required.
@@ -289,7 +306,7 @@ def merge_lexemes(source: str, target: str, summary: str = None, is_bot: bool =
def remove_claims(claim_id: str, summary: str = None, baserevid: int = None, is_bot: bool = False, **kwargs: Any) -> Dict:
"""
- Delete an item
+ Delete a claim from an entity
:param claim_id: One GUID or several (pipe-separated) GUIDs identifying the claims to be removed. All claims must belong to the same entity.
:param summary: Summary for the edit. Will be prepended by an automatically generated comment.
diff --git a/wikibaseintegrator/wbi_login.py b/wikibaseintegrator/wbi_login.py
index 4ce113af..51da7c66 100644
--- a/wikibaseintegrator/wbi_login.py
+++ b/wikibaseintegrator/wbi_login.py
@@ -1,5 +1,5 @@
"""
-Login class for Wikidata. Takes username and password and stores the session cookies and edit tokens.
+Login class for Wikidata. Takes authentication parameters and stores the session cookies and edit tokens.
"""
import logging
import time
@@ -105,6 +105,16 @@ class OAuth2(_Login):
@wbi_backoff()
def __init__(self, consumer_token: str = None, consumer_secret: str = None, mediawiki_api_url: str = None, mediawiki_rest_url: str = None, token_renew_period: int = 1800,
user_agent: str = None):
+ """
+ This class is used to interact with the OAuth2 API.
+
+ :param consumer_token: The consumer token
+ :param consumer_secret: The consumer secret
+ :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata)
+ :param mediawiki_rest_url: The URL to the Mediawiki REST API (default Wikidata)
+ :param token_renew_period: Seconds after which a new token should be requested from the Wikidata server
+ :param user_agent: UA string to use for API requests.
+ """
mediawiki_rest_url = str(mediawiki_rest_url or config['MEDIAWIKI_REST_URL'])
@@ -124,6 +134,19 @@ class OAuth1(_Login):
@wbi_backoff()
def __init__(self, consumer_token: str = None, consumer_secret: str = None, access_token: str = None, access_secret: str = None, callback_url: str = 'oob',
mediawiki_api_url: str = None, mediawiki_index_url: str = None, token_renew_period: int = 1800, user_agent: str = None):
+ """
+ This class is used to interact with the OAuth1 API.
+
+ :param consumer_token: The consumer token
+ :param consumer_secret: The consumer secret
+ :param access_token: The access token
+ :param access_secret: The access secret
+ :param callback_url: The callback URL used to finalize the handshake
+ :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata)
+ :param mediawiki_index_url: The URL to the Mediawiki index (default Wikidata)
+ :param token_renew_period: Seconds after which a new token should be requested from the Wikidata server
+ :param user_agent: UA string to use for API requests.
+ """
mediawiki_index_url = str(mediawiki_index_url or config['MEDIAWIKI_INDEX_URL'])
@@ -155,6 +178,7 @@ def continue_oauth(self, oauth_callback_data: str = None) -> None:
"""
Continuation of OAuth procedure. Method must be explicitly called in order to complete OAuth. This allows
external entities, e.g. websites, to provide tokens through callback URLs directly.
+
:param oauth_callback_data: The callback URL received to a Web app
:type oauth_callback_data: bytes
:return:
@@ -184,6 +208,15 @@ def continue_oauth(self, oauth_callback_data: str = None) -> None:
class Login(_Login):
@wbi_backoff()
def __init__(self, user: str = None, password: str = None, mediawiki_api_url: str = None, token_renew_period: int = 1800, user_agent: str = None):
+ """
+ This class is used to log in with a bot password
+
+ :param user: The user of the bot password (format @)
+ :param password: The password generated byt the Mediawiki
+ :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata)
+ :param token_renew_period: Seconds after which a new token should be requested from the Wikidata server
+ :param user_agent: UA string to use for API requests.
+ """
mediawiki_api_url = str(mediawiki_api_url or config['MEDIAWIKI_API_URL'])
session = Session()
@@ -224,6 +257,15 @@ def __init__(self, user: str = None, password: str = None, mediawiki_api_url: st
class Clientlogin(_Login):
@wbi_backoff()
def __init__(self, user: str = None, password: str = None, mediawiki_api_url: str = None, token_renew_period: int = 1800, user_agent: str = None):
+ """
+ This class is used to log in with a user account
+
+ :param user: The username
+ :param password: The password
+ :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata)
+ :param token_renew_period: Seconds after which a new token should be requested from the Wikidata server
+ :param user_agent: UA string to use for API requests.
+ """
mediawiki_api_url = str(mediawiki_api_url or config['MEDIAWIKI_API_URL'])
session = Session()
diff --git a/wikibaseintegrator/wikibaseintegrator.py b/wikibaseintegrator/wikibaseintegrator.py
index 05deca34..859babc1 100644
--- a/wikibaseintegrator/wikibaseintegrator.py
+++ b/wikibaseintegrator/wikibaseintegrator.py
@@ -1,3 +1,6 @@
+"""
+Main class of the Library.
+"""
from __future__ import annotations
from typing import TYPE_CHECKING
@@ -14,6 +17,12 @@
class WikibaseIntegrator:
def __init__(self, is_bot: bool = False, login: Login = None):
+ """
+ This function initializes a WikibaseIntegrator instance to quickly access different entity type instances.
+
+ :param is_bot: declare if the bot flag must be set when you interact with the Mediawiki API.
+ :param login: a wbi_login instance needed when you try to access a restricted Mediawiki instance.
+ """
# Runtime variables
self.is_bot = is_bot or False
self.login = login