Refactor docs.

README.md

@@ -0,0 +1,99 @@
+<center>
+  <a href="https://github.com/riga/order">
+    <img src="https://raw.githubusercontent.com/riga/order/master/logo240.png" />
+  </a>
+</center>
+
+
+<!-- marker-after-logo -->
+
+
+[![Documentation status](https://readthedocs.org/projects/python-order/badge/?version=latest)](http://python-order.readthedocs.io/en/latest)
+[![Lint and test](https://github.com/riga/order/actions/workflows/lint_and_test.yml/badge.svg)](https://github.com/riga/order/actions/workflows/lint_and_test.yml)
+[![Code coverge](https://codecov.io/gh/riga/order/branch/master/graph/badge.svg?token=SNFRGYOITJ)](https://codecov.io/gh/riga/order)
+[![Package version](https://img.shields.io/pypi/v/order.svg?style=flat)](https://pypi.python.org/pypi/order)
+[![License](https://img.shields.io/github/license/riga/order.svg)](https://github.com/riga/order/blob/master/LICENSE)
+[![PyPI downloads](https://img.shields.io/pypi/dm/order.svg)](https://pypi.python.org/pypi/order)
+[![Open in colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/riga/order/blob/master/examples/intro.ipynb)
+[![Open in binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/riga/order/master?filepath=examples%2Fintro.ipynb)
+
+If you're designing a high-energy physics analysis (e.g. with data recorded by an [LHC](https://home.cern/topics/large-hadron-collider) experiment at [CERN](http://home.cern), manual bookkeeping of external data can get complicated quite fast.
+*order* provides a pythonic class collection that helps you structuring
+
+- analyses,
+- MC campaigns,
+- datasets,
+- physics process and cross sections,
+- channels,
+- categories,
+- variables, and
+- systematic shifts.
+
+
+<!-- marker-after-header -->
+
+
+## Getting started
+
+See the [intro.ipynb](https://github.com/riga/order/blob/master/examples/intro.ipynb) notebook for an introduction to the most important classes and an example setup of a small analysis.
+You can also run the notebook interactively on colab or binder:
+
+[![Open in colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/riga/order/blob/master/examples/intro.ipynb)
+[![Open in binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/riga/order/master?filepath=examples%2Fintro.ipynb)
+
+You can find the full [API documentation on readthedocs](http://python-order.readthedocs.io).
+
+
+<!-- marker-after-getting-started -->
+
+
+## Projects using order
+
+- [uhh-cms/cmsdb](https://github.com/uhh-cms/cmsdb)
+- tba
+
+
+## Installation and dependencies
+
+Install *order* via [pip](https://pypi.python.org/pypi/order):
+
+```shell
+pip install order
+```
+
+The only dependencies are [scinum](https://pypi.python.org/pypi/scinum) and [six](https://pypi.python.org/pypi/six) (Python 2 support that will be dropped soon), which are installed with the above command.
+
+
+## Contributing and testing
+
+If you like to contribute, feel free to open a pull request 🎉.
+Just make sure to add new test cases and run them via:
+
+```shell
+python -m unittest tests
+```
+
+In general, tests should be run for Python 2.7, 3.6 - 3.11.
+To run tests in a docker container, do
+
+```shell
+# run the tests
+./tests/docker.sh python:3.9
+
+# or interactively by adding a flag "1" to the command
+./tests/docker.sh python:3.9 1
+> pip install -r requirements.txt
+> python -m unittest tests
+```
+
+In addition, [PEP 8](https://www.python.org/dev/peps/pep-0008) compatibility should be checked with [flake8](https://pypi.org/project/flake8):
+
+```shell
+flake8 order tests setup.py
+```
+
+
+## Development
+
+- Source hosted at [GitHub](https://github.com/riga/order)
+- Report issues, questions, feature requests on [GitHub Issues](https://github.com/riga/order/issues)

docs/_static/styles_sphinx_book_theme.css

@@ -0,0 +1,11 @@
+/* sphinx_rtd_theme styles */
+
+div#site-navigation img.logo {
+    width: 240px !important;
+    height: 85px !important;
+    max-height: none !important;
+}
+
+div#site-navigation div.navbar_extra_footer {
+    display: none;
+}

docs/conf.py

@@ -29,12 +29,7 @@
 
 html_title = "{} v{}".format(project, version)
 html_logo = "../logo240.png"
-html_sidebars = {"**": [
-    "about.html",
-    "localtoc.html",
-    "searchbox.html",
-]}
-html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_book_theme"
 html_theme_options = {}
 if html_theme == "sphinx_rtd_theme":
     html_theme_options.update({
@@ -46,7 +41,16 @@
     html_theme_options.update({
         "github_user": "riga",
         "github_repo": "order",
-        "travis_button": True,
+    })
+elif html_theme == "sphinx_book_theme":
+    html_theme_options.update({
+        "logo_only": True,
+        "home_page_in_toc": True,
+        "show_navbar_depth": 2,
+        "repository_url": "https://github.com/riga/order",
+        "use_repository_button": True,
+        "use_issues_button": True,
+        "use_edit_page_button": True,
     })
 
 extensions = [
@@ -55,6 +59,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.autosectionlabel",
     "autodocsumm",
+    "myst_parser",
     "pydomain_patch",
 ]
 
@@ -63,5 +68,5 @@
 
 def setup(app):
     app.add_css_file("styles_common.css")
-    if html_theme in ("sphinx_rtd_theme", "alabaster"):
+    if html_theme in ("sphinx_rtd_theme", "alabaster", "sphinx_book_theme"):
         app.add_css_file("styles_{}.css".format(html_theme))

docs/index.rst

@@ -1,30 +1,17 @@
 **order**
 =========
 
-.. toctree::
-   :hidden:
-
-   self
-
-.. include:: ../README.rst
-   :start-after: marker-after-logo
-   :end-before: marker-after-header
-
-
-Getting started
----------------
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+   :start-after: <!-- marker-after-logo -->
+   :end-before: <!-- marker-after-header -->
 
 .. toctree::
    :maxdepth: 1
 
    quickstart
    api/index
 
-See the `intro.ipynb <https://github.com/riga/order/blob/master/examples/intro.ipynb>`__ notebook for an introduction to the most important classes and an example setup of a small analysis.
-You can also run the notebook interactively on colab or binder:
-
-|colab| |binder|
-
-
-.. include:: ../README.rst
-   :start-after: marker-after-getting-started
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+   :start-after: <!-- marker-after-getting-started -->

docs/quickstart.rst

@@ -12,9 +12,6 @@ Open the `intro.ipynb <https://github.com/riga/order/blob/master/examples/intro.
 2. Properties implement type checks and, where applicable, conversions! Assigments such as ``my_object.some_string_attribute = 123`` (can) immediately fail. This way, type ambiguities during analysis execution are avoided and detected early.
 3. The code style is `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`__ compatible (checked via `flake8 <https://pypi.org/project/flake8/>`__).
 
-.. contents:: Contents
-   :local:
-
 
 *UniqueObject* and *UniqueObjectIndex*
 --------------------------------------
@@ -439,7 +436,7 @@ Copying objects
 ---------------
 
 Most classes inherit from the :py:class:`~order.mixins.CopyMixin`.
-As a result, instances can be copied through the :py:meth:`~order.mixins.CopyMixin.copy` method defined on the mixin class itself.
+As a result, instances can be copied via :py:meth:`~order.mixins.CopyMixin.copy`, returning a full, deep copy including relations to other objects, or via :py:meth:`~order.mixins.CopyMixin.copy_shallow` which copies everything *but* those relations.
 You can pass keyword arguments to configure / overwrite certain attributes of the copied object instead of copying them from the original one.
 
 The copy mechanism can be demonstrated using :py:class:`~order.variable.Variable`'s.

requirements_docs.txt

@@ -3,4 +3,6 @@ six
 
 sphinx>=5.0,<6
 sphinx_rtd_theme
+sphinx_book_theme
 autodocsumm==0.2.*
+myst-parser~=0.18

setup.py

@@ -35,7 +35,7 @@
 
 
 # read the readme file
-with open(os.path.join(this_dir, "README.rst"), "r") as f:
+with open(os.path.join(this_dir, "README.md"), "r") as f:
     long_description = f.read()
 
 
@@ -61,6 +61,7 @@
     keywords=keywords,
     classifiers=classifiers,
     long_description=long_description,
+    long_description_content_type="text/markdown",
     install_requires=install_requires,
     python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, <4",
     zip_safe=False,