updated documentation

docs/api_reference.rst

@@ -0,0 +1,9 @@
+API Reference
+=============
+
+.. automodule:: egttools
+    :members:
+    :special-members:
+    :undoc-members:
+    :show-inheritance:
+    :exclude-members: __weakref__, __doc__, __module__, __dict__, __members__, __getstate__, __setstate__

docs/conf.py

@@ -16,23 +16,19 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import git
+import github
+import requests
+
+import io
 import os
+import subprocess
 import sys
+import tempfile
+import zipfile
 
 on_rtd = os.environ.get('READTHEDOCS') == 'True'
 
-
-# -- Project information -----------------------------------------------------
-
-project = 'EGTtools'
-copyright = '2020, Elias Fernández'
-author = 'Elias Fernández'
-
-# The short X.Y version
-version = ''
-# The full version, including alpha/beta/rc tags
-release = '0.1.0'
-
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -57,6 +53,7 @@
     'sphinx.ext.githubpages',
     'recommonmark',
     'nbsphinx',
+    'pybind11_docstrings',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -71,6 +68,42 @@
 # The master toctree document.
 master_doc = 'index'
 
+# -- Project information -----------------------------------------------------
+
+project = 'EGTtools'
+copyright = '2019-2021, Elias Fernández'
+author = 'Elias Fernández'
+
+if on_rtd:
+    rtd_version = os.environ.get('READTHEDOCS_VERSION')
+    branch = 'master' if rtd_version == 'latest' else rtd_version
+
+    github_token = os.environ['GITHUB_TOKEN']
+    head_sha = git.Repo(search_parent_directories=True).head.commit.hexsha
+    g = github.Github()
+    runs = g.get_repo('YannickJadoul/Parselmouth').get_workflow("wheels.yml").get_runs(branch=branch)
+    artifacts_url = next(r for r in runs if r.head_sha == head_sha).artifacts_url
+
+    archive_download_url = \
+        next(artifact for artifact in requests.get(artifacts_url).json()['artifacts'] if
+             artifact['name'] == 'rtd-wheel')[
+            'archive_download_url']
+    artifact_bin = io.BytesIO(
+        requests.get(archive_download_url, headers={'Authorization': f'token {github_token}'}, stream=True).content)
+
+    with zipfile.ZipFile(artifact_bin) as zf, tempfile.TemporaryDirectory() as tmpdir:
+        assert len(zf.namelist()) == 1
+        zf.extractall(tmpdir)
+        subprocess.check_call(
+            [sys.executable, '-m', 'pip', 'install', '--force-reinstall', tmpdir + '/' + zf.namelist()[0]])
+
+import egttools
+
+# The short X.Y version
+version = '.'.join(egttools.__version__.split('.')[:2])
+# The full version, including alpha/beta/rc tags
+release = egttools.__version__
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -89,12 +122,33 @@
 # Autodoc configuration
 autodoc_member_order = 'groupwise'
 
+# Intersphinx configuration
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
+                       'numpy': ('https://numpy.org/doc/stable/', None)}
+
+efault_role = 'py:obj'
+nitpicky = True
+nitpick_ignore = [('py:class', 'pybind11_builtins.pybind11_object'),
+                  ('py:class', 'List'),
+                  ('py:class', 'Positive'),
+                  ('py:class', 'NonNegative'),
+                  ('py:class', 'numpy.float64'),
+                  ('py:class', 'numpy.complex128'),
+                  ('py:obj', 'List')]
+
+if on_rtd:
+    branch_or_tag = branch or 'v{}'.format(release)
+else:
+    rev_parse_name = subprocess.check_output(['git', 'rev-parse', '--abbrev-ref', 'HEAD']).decode('ascii').strip()
+    branch_or_tag = rev_parse_name if rev_parse_name != 'HEAD' else 'v{}'.format(release)
+
+
 # -- 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 = 'default' if on_rtd else 'sphinx_rtd_theme'
 html_logo = "images/logo.png"
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -178,6 +232,9 @@
 
 # Bibliographic Dublin Core info.
 epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright
 
 # The unique identifier of the text. This can be a ISBN number
 # or the project homepage.
@@ -195,11 +252,6 @@
 
 # -- Options for intersphinx extension ---------------------------------------
 
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
-                       'numpy': ('https://docs.scipy.org/doc/numpy', None),
-                       'tgt': ('https://textgridtools.readthedocs.io/en/stable', None)}
-
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.

docs/index.rst

@@ -8,20 +8,27 @@
 EGTtools -- Toolbox for Evolutionary Game Theory
 ================================================
 
-**EGTtools** provides a centralized repository with analytical
-and numerical methods to study/model game theoretical problems under the Evolutionary
-Game Theory (EGT) framework.
+**EGTtools** provides a centralized repository with analytical and numerical methods to study/model game theoretical
+problems under the Evolutionary Game Theory (EGT) framework.
 
-This library is implemented both in Python and C++ (with Python bindings) in order to
-provide optimized computational methods that can run in parallel in a reasonable time.
+This library is composed of two parts:
+
+- a set of analytical methods implemented in Python 3
+- a set of computational methods implemented in C++ with (Python 3 bindings)
+
+The second typed is used in cases where the state space is too big to solve analytically, and thus require estimating
+the model parameters through monte-carlo simulations. The C++ implementation provides optimized computational methods
+that can run in parallel in a reasonable time, while Python bindings make the methods easily accecible to a larger range
+of researchers.
 
 .. toctree::
    :maxdepth: 2
    :caption: Getting Started
 
-   installation
    examples
 
+   api_reference
+
 Citing EGTtools
 ------------------
 

docs/pybind11_docstrings.py

@@ -0,0 +1,12 @@
+import re
+
+RE_ARGS_KWARGS = re.compile(r'(?<![*\\])\*args|(?<!\\)\*\*kwargs')
+
+
+def fix_args_kwargs(app, what, name, obj, options, lines):
+    for i, line in enumerate(lines):
+        lines[i] = RE_ARGS_KWARGS.sub(lambda m: m.group().replace('*', '\\*'), line)
+
+
+def setup(app):
+    app.connect('autodoc-process-docstring', fix_args_kwargs)

docs/requirements.txt

@@ -1,8 +1,16 @@
+Sphinx>=3
+sphinx_rtd_theme
+
+GitPython
+PyGithub
+requests
+
 -r ../requirements.txt
 
-Sphinx==3.2.1
 ipykernel
 ipywidgets
 nbsphinx
 recommonmark
-sphinx_rtd_theme
+
+
+-r examples/requirements.txt

egttools/__init__.py

@@ -10,3 +10,5 @@
     raise ImportError("Numerical module cannot be imported. It might not have been compiled correctly.")
 else:
     from egttools.numerical import (sample_simplex, calculate_nb_states, calculate_state, )
+    from egttools.numerical import __version__
+    from egttools.numerical import VERSION

src/egttools.cpp

@@ -24,6 +24,7 @@
 #define STR(s) #s
 
 namespace py = pybind11;
+using namespace std::string_literals;
 using namespace egttools;
 using PairwiseComparison = egttools::FinitePopulations::PairwiseMoran<egttools::Utils::LRUCache<std::string, double>>;