Update docs for "add_additional_resource" and other fixes

.github/workflows/tests.yml

@@ -25,7 +25,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        root-version: ["6.24", "6.26"]
+        root-version: ["6.24", "6.26", "6.28"]
         python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
         exclude:
           - root-version: "6.24"
@@ -34,9 +34,13 @@ jobs:
             python-version: "3.6"
           - root-version: "6.26"
             python-version: "3.7"
+          - root-version: "6.28"
+            python-version: "3.6"
+          - root-version: "6.28"
+            python-version: "3.7"
         include:
           - os: macos-latest
-            root-version: "6.26"
+            root-version: "6.28"
             python-version: "3.10"
 
     steps:

.gitignore

@@ -1,6 +1,8 @@
 # output from examples
 examples/submission.tar.gz
 examples/example_output/
+examples/output/
+examples/correlation.root
 
 # test output
 submission.tar.gz

.readthedocs.yml

@@ -5,19 +5,26 @@
 # Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/conf.py
-
-# Build documentation with MkDocs
-#mkdocs:
-#  configuration: mkdocs.yml
+  # Fail on all warnings to avoid broken references
+  fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all
 
-# Optionally set the version of Python and requirements required to build your docs
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
-  version: 3.7
   install:
-    - requirements: docs/requirements.txt
+  - requirements: docs/requirements.txt
+  - method: pip
+    path: .

README.md

@@ -1,6 +1,6 @@
 # hepdata_lib
 
-[![DOI](https://zenodo.org/badge/129248575.svg)](https://zenodo.org/badge/latestdoi/129248575)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1217998.svg)](https://doi.org/10.5281/zenodo.1217998)
 [![PyPI version](https://badge.fury.io/py/hepdata-lib.svg)](https://badge.fury.io/py/hepdata-lib)
 [![Actions Status](https://github.com/HEPData/hepdata_lib/workflows/tests/badge.svg)](https://github.com/HEPData/hepdata_lib/actions)
 [![Coverage Status](https://codecov.io/gh/HEPData/hepdata_lib/graph/badge.svg?branch=master)](https://codecov.io/gh/HEPData/hepdata_lib?branch=master)
@@ -9,6 +9,10 @@
 
 Library for getting your data into HEPData
 
+- Documentation: https://hepdata-lib.readthedocs.io
+
+This code works with Python 3.6, 3.7, 3.8, 3.9 or 3.10.
+
 ## Installation
 
 It is highly recommended you install `hepdata_lib` into a [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/).
@@ -53,11 +57,25 @@ Unpacking the image can take a few minutes the first time you use it. Please be
 
 There are a few more examples available that can directly be run using the [binder](https://mybinder.org/) links below or using [SWAN](https://swan.cern.ch/) (CERN-only, please use LCG release LCG_94 or later) and selecting the corresponding notebook manually:
 
-- [Reading in text files](examples/Getting_started.ipynb) [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/Getting_started.ipynb)
-- [Reading in a CMS combine ntuple](examples/combine_limits.ipynb) [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/combine_limits.ipynb)
-- [Reading in ROOT histograms](examples/reading_histograms.ipynb) [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/reading_histograms.ipynb)
-- [Reading a correlation matrix](examples/correlation.ipynb) [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/correlation.ipynb)
-- [Reading TGraph and TGraphError from '.C' files](examples/read_c_file.ipynb) [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/read_c_file.ipynb)
+- [Reading in text files](https://github.com/HEPData/hepdata_lib/blob/master/examples/Getting_started.ipynb)\
+[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/Getting_started.ipynb)
+<br/><br/>
+
+- [Reading in a CMS combine ntuple](https://github.com/HEPData/hepdata_lib/blob/master/examples/combine_limits.ipynb)\
+[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/combine_limits.ipynb)
+<br/><br/>
+
+- [Reading in ROOT histograms](https://github.com/HEPData/hepdata_lib/blob/master/examples/reading_histograms.ipynb)\
+[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/reading_histograms.ipynb)
+<br/><br/>
+
+- [Reading a correlation matrix](https://github.com/HEPData/hepdata_lib/blob/master/examples/correlation.ipynb)\
+[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/correlation.ipynb)
+<br/><br/>
+
+- [Reading TGraph and TGraphError from '.C' files](https://github.com/HEPData/hepdata_lib/blob/master/examples/read_c_file.ipynb)
+[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/master?filepath=examples/read_c_file.ipynb)
+<br/><br/>
 
 ## External dependencies
 

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W --keep-going
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = hepdata_lib
 SOURCEDIR     = .

docs/conf.py

@@ -35,7 +35,7 @@ def __getattr__(cls, name):
 # -- Project information -----------------------------------------------------
 
 project = 'hepdata_lib'
-copyright = '2018-2022, Andreas Albert, Clemens Lange'
+copyright = '2018-2023, Andreas Albert, Clemens Lange'
 author = 'Andreas Albert, Clemens Lange'
 
 # The short X.Y version
@@ -55,7 +55,7 @@ def __getattr__(cls, name):
 # ones.
 extensions = [
     'sphinx.ext.githubpages',
-    'm2r2',
+    'sphinx_mdinclude',
     'sphinx.ext.autodoc'
 ]
 
@@ -76,7 +76,7 @@ def __getattr__(cls, name):
 #
 # 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
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -103,7 +103,7 @@ def __getattr__(cls, name):
 # 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']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/contributing.rst

@@ -34,7 +34,7 @@ The files in which the versions are updated as well as the current version can b
 .. _sec-dev-pypi:
 
 Uploading to PyPI
------------------------------
+-----------------
 
 Once a new version has been tagged, the package should be uploaded to the Python Package Index (PyPI_).
 For the markdown formatting to work, ``twine>=1.11.0`` is required.
@@ -72,7 +72,7 @@ You should then find the new version at `this location`_. You need to be a maint
 .. _python packaging documentation: https://packaging.python.org/tutorials/packaging-projects/
 
 Creating a new release automatically via an issue
------------------------------
+-------------------------------------------------
 
 Opening an new issue automatically creates a new release if:
 

docs/dev.rst

@@ -1,21 +1,22 @@
 Developer information
-======================
+=====================
 
 The testing system
---------------------
+------------------
 
 While further developing the code base, we want to ensure that any changes we make do not accidentally break existing functionality. For this purpose, we use continuous integration via GitHub Actions_. Practically, this means that we define a set of test code that is automatically run in a predefined environment every time we push to a branch or create a pull request. If the test code runs successfully, we know that everything works as expected.
 
-To run the tests, move into the ``hepdata_lib`` directory and run
+To run the tests, move into the ``hepdata_lib`` directory while in your virtual environment and run
 
 ::
 
-    python setup.py test
+    pip install -e ".[test]"
+    pytest tests
 
 It is a good idea to run the tests manually to ensure that your changes do not cause any issues.
 
 Definition of test cases
-+++++++++++++++++++++++++
+++++++++++++++++++++++++
 
 Test cases are defined in the ``test`` subfolder of the repository. Independent sets of test code are defined in individual files in that directory, with each files being named like ``test_*.py``.
 
@@ -40,12 +41,12 @@ If all functions run without raising exceptions, the test is considered to be pa
 
 
 When to test
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~
 
 Tests should be added any time functionality is added. If functionality is modified, so should the tests.
 
 What to test
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~
 
 Generally, the tests should ensure that the code behaves as expected, whatever that may mean. They should be sufficiently rigorous to make sure that nothing can break silently, and that outputs are correct.
 
@@ -57,7 +58,7 @@ Broad inspiration for aspects to check:
 
 
 How to test
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~
 
 The ``TestCase`` base class provides functionality to help implement simple checks to verify the behavior. A test can immediately be made to fail by calling ``self.fail()``. For convenience, additional functions like ``assertTrue``, ``assertFalse``, etc. are provided, which work like normal python assertions. If the assertion fails, the test is considered to be failed. Additionally, the ``assertRaises`` method can be used as a context to ensure that exceptions are raised as expected. Here's a simple example:
 
@@ -95,10 +96,28 @@ Note that this is an overly simple example case: In a real testing case, you sho
 
 Check out the unittest package documentation_ for details of the available testing functionality.
 
+.. _Actions: https://docs.github.com/en/actions
+.. _documentation: https://docs.python.org/2/library/unittest.html#unittest.TestCase
+
 
+Building the documentation
+--------------------------
 
+After installing the ``hepdata_lib`` package, move into the ``hepdata_lib/docs`` directory and install the additional necessary packages into your virtual environment:
 
+::
 
+    pip install -r requirements.txt
 
-.. _Actions: https://docs.github.com/en/actions
-.. _documentation: https://docs.python.org/2/library/unittest.html#unittest.TestCase
+Then you can build the documentation locally with Sphinx using ``make html`` and view the output by opening a web browser at ``_build/html/index.html``.
+
+
+Analysing the code
+------------------
+
+::
+
+    pylint hepdata_lib/*.py
+    pylint tests/*.py --rcfile=tests/pylintrc
+
+These commands are run by GitHub Actions, so you should first check locally that no issues are flagged.

docs/requirements.txt

@@ -1,4 +1,4 @@
-m2r2==0.3.3
+Sphinx<7
 sphinx_rtd_theme
 docutils==0.19
-mistune<2.0.0
+sphinx-mdinclude

docs/setup.rst

@@ -47,7 +47,7 @@ If you would like to develop the code, you need to install the package from the
 ::
 
     cd $SOMEPATH
-    git clone git@github.com:HEPData/hepdata_lib.git
+    git clone https://github.com/HEPData/hepdata_lib.git
 
     workon myhepdata # activate virtual environment!
     pip install -e $SOMEPATH/hepdata_lib
@@ -92,6 +92,15 @@ You can always activate the virtual environment in another shell by calling the
     workon hepdata_git
     python myscript.py # Execute script using development branch
 
+Alternatively, if you don't want to install the additional virtualenv_ and virtualenvwrapper_ packages, you can simply
+use the venv_ module from the Python standard library.
+
+::
+
+    python3 -m venv env
+    source env/bin/activate
+
+.. _venv: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
 
 Setup on lxplus with CMSSW
 --------------------------

docs/source/hepdata_lib.rst

@@ -9,6 +9,16 @@ Module contents
     :undoc-members:
     :show-inheritance:
 
+.. automodule:: hepdata_lib.c_file_reader
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: hepdata_lib.helpers
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 .. automodule:: hepdata_lib.root_utils
     :members:
     :undoc-members: