From 85d9cb70719869f2df1e9a035bade330aa73af54 Mon Sep 17 00:00:00 2001
From: Paul Natsuo Kishimoto <mail@paul.kishimoto.name>
Date: Sun, 18 Jul 2021 15:20:57 +0200
Subject: [PATCH 1/2] Use np.isscalar(), not deprecated ixmp.utils.isscalar
---
message_ix/core.py | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/message_ix/core.py b/message_ix/core.py
index 4e054475f..70ecdeb4b 100755
--- a/message_ix/core.py
+++ b/message_ix/core.py
@@ -5,8 +5,9 @@
from warnings import warn
import ixmp
+import numpy as np
import pandas as pd
-from ixmp.utils import as_str_list, isscalar
+from ixmp.utils import as_str_list
log = logging.getLogger(__name__)
@@ -274,7 +275,7 @@ def recurse(k, v, parent="World"):
recurse(_k, _v, parent=_parent)
level = k
- children = [v] if isscalar(v) else v
+ children = [v] if np.isscalar(v) else v
for child in children:
hierarchy.append([level, child, parent])
nodes.append(child)
From 4eaef6f733ba74b7fb4526a8692a858b2d78550f Mon Sep 17 00:00:00 2001
From: Paul Natsuo Kishimoto <mail@paul.kishimoto.name>
Date: Sun, 18 Jul 2021 15:40:09 +0200
Subject: [PATCH 2/2] Update doc/contributing.rst
---
doc/conf.py | 1 +
doc/contributing.rst | 80 +++++++++++++++++++++++++++++++++-----------
2 files changed, 61 insertions(+), 20 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index 0c40057af..da67b1bfa 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -121,6 +121,7 @@
"pint": ("https://pint.readthedocs.io/en/stable/", None),
"pyam": ("https://pyam-iamc.readthedocs.io/en/stable/", None),
"python": ("https://docs.python.org/3/", None),
+ "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
}
# -- Options for sphinx.ext.mathjax ----------------------------------------------------
diff --git a/doc/contributing.rst b/doc/contributing.rst
index 312af90d8..d9c390e35 100644
--- a/doc/contributing.rst
+++ b/doc/contributing.rst
@@ -176,36 +176,76 @@ Current practice for the ``ixmp``, ``message_ix``, and ``message_data`` reposito
Code style
==========
-- Follow the `seven rules of a great Git commit message <https://chris.beams.io/posts/git-commit/#seven-rules>`_ for commit messages and PR titles.
-- Apply the following to new or modified **Python** code::
+- For both **commit messages** and **pull request (PR) titles**, memorize and use the `“7 rules of a great Git commit message” <https://chris.beams.io/posts/git-commit/#seven-rules>`_.
- isort -rc . && black . && mypy . && flake8
+- **Python** code:
- Links to the documentation for these tools:
+ - Follow the `PEP 8 naming conventions <https://www.python.org/dev/peps/pep-0008/#naming-conventions>`_.
- - `isort <https://pypi.org/project/isort/>`_: sorts import lines at the top of code files in a consistent way.
- - `black <https://black.readthedocs.io>`_: applies consistent code style & formatting.
- Plugins are available for popular code editors.
- - `mypy <https://mypy.readthedocs.io>`_: checks typing for inconsistencies.
- - `flake8 <https://flake8.pycqa.org>`_: check code style against `PEP 8 <https://www.python.org/dev/peps/pep-0008>`_.
+ - Apply the following to all code::
- The ``lint`` continuous integration workflow runs these on every pull request.
- PRs that fail the checks must be corrected before they can be merged.
+ isort -rc . && black . && mypy . && flake8
-- Write docstrings in the `numpydoc <https://numpydoc.readthedocs.io/en/latest/format.html>`_ style.
-- For new or modified **R** code, follow the style of the existing code base.
-- Jupyter notebooks (:file:`.ipynb`): see :doc:`contrib/tutorial`.
-- For **documentation** in ReStructuredText formats, in :file:`doc/*.rst` and inline in :file:`message_ix/model/*.gms` files:
+ Links to the documentation for these tools:
+
+ - `isort <https://pypi.org/project/isort/>`_: sorts import lines at the top of code files in a consistent way.
+ - `black <https://black.readthedocs.io>`_: applies consistent code style & formatting.
+ Plugins are available for popular code editors.
+ - `mypy <https://mypy.readthedocs.io>`_: checks typing for inconsistencies.
+ - `flake8 <https://flake8.pycqa.org>`_: check code style against `PEP 8 <https://www.python.org/dev/peps/pep-0008>`_.
- - Start each sentence on a new line.
- - Do not hard-wrap sentences.
- - Ensure Sphinx does not give warnings about ReST syntax for new or modified documentation.
+ The ``lint`` continuous integration workflow runs these on every pull request.
+ PRs that fail the checks must be corrected before they can be merged.
+
+ - Add type hints to new or changed functions, methods, and global variables.
- **GAMS** code:
- - Wrap lines at 121 characters, except for inline documentation (see above).
+ - Wrap lines at 121 characters, except for inline documentation (see above).
+
+- **R** code: follow the style of the existing code base.
+- Jupyter notebooks (:file:`.ipynb`): see :doc:`contrib/tutorial`.
+- Other (file names, CLI, etc.): follow the style of the existing code base, e.g.:
+
+ - Use lower-case file names and extensions.
+ - Except for Python source files, prefer hyphens to underscores.
+
+Documentation
+-------------
+
+- Write documentation in ReStructuredText formats for:
+
+ 1. Python docstrings.
+ 2. Documentation pages, :file:`doc/*.rst`.
+ 3. Inline documentation in :file:`message_ix/model/*.gms` files.
+
+ For (2) and (3), start each sentence on a new line, and do not hard-wrap sentences.
+ For (1), wrap at the same 88 characters as :command:`black` enforces for code.
+
+- Ensure Sphinx does not give warnings about ReST syntax for new or modified documentation.
+
+- Use :mod:`sphinx.ext.intersphinx` (click for docs) to create cross-links within one project's documentation, or across projects.
+
+ - Understand the use of the ``~`` and ``.`` characters to resolve references across the project. See :ref:`sphinx:xref-syntax` in the Sphinx docs.
+ - See example usage in existing code.
+ - Check that intersphinx links are correctly resolved, by building the docs and attempting to click new or modified links.
+
+- Write docstrings in the `numpydoc <https://numpydoc.readthedocs.io/en/latest/format.html>`_ style.
+
+ Use single backticks to refer to function arguments, and asterisks for italics:
+
+ .. code-block:: python
+
+ def func(foo: str, bar: str) -> float:
+ """Perform some action.
+
+ If `foo` and `bar` have the same value, ``42.1`` is returned. *Nice!*
+ """
+
+References:
-- Other (file names, CLI, etc.): follow the style of the existing code base.
+- :doc:`sphinx:usage/restructuredtext/basics` in the Sphinx docs.
+- https://docutils.sourceforge.io/docs/user/rst/quickref.html
Manage issues and pull requests