Merge branch 'master' into nsoblath/issue_163

.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+
+python:
+  version: "3.7"
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - test
+        - dev
+    - method: setuptools
+      path: .

VERSION

@@ -10,4 +10,4 @@
 #   The third number is the Micro number of the release
 #     - Only increment the Micro number when:
 #       - Fixing bugs, adding tests, changing packaging
-3_2_0
+3_2_1

apbs/__init__.py

@@ -1,3 +1,5 @@
+from ._version import __version__  # noqa: F401
+
 header = """
 
 ----------------------------------------------------------------------

apbs/_version.py

@@ -0,0 +1,8 @@
+"""APBS Version number.
+Store the version here so:
+
+* we don't load dependencies by storing it in :file:`__init__.py`
+* we can import it in setup.py for the same reason
+* we can import it into your module
+"""
+__version__ = "3.2.1"

docs/CMakeLists.txt

@@ -2,14 +2,6 @@
 # TODO:  Generate license.html
 ################################################################################
 
-file(READ conf.py.in CONFPYDATA)
-message(STATUS "Update RTD conf.py to VERSION ${CMAKE_PROJECT_VERSION}")
-STRING(REGEX REPLACE __PROJECT_VERSION__ ${CMAKE_PROJECT_VERSION} CONFPYDATA ${CONFPYDATA})
-message(STATUS "Update RTD conf.py to YEAR ${COMPILE_YEAR}")
-STRING(REGEX REPLACE __YEAR__ ${COMPILE_YEAR} CONFPYDATA ${CONFPYDATA})
-file(WRITE conf.py ${CONFPYDATA})
-
-
 ################################################################################
 # NOTE: Don't do this unless you have LaTex and way too much time to kill
 ################################################################################

docs/ChangeLog.md

@@ -40,6 +40,7 @@ These are notes for APBS version 3.2
 * Fixed miscellaneous Windows build issues.
 * Update the build configurations for the Pythons libraries.
 * Removed unused files that no longer worked (e.g. Makefile in example directories)
+* Updated Sphinx configuration to build API documentation
 
 ### Notes
 

docs/conf.py

@@ -10,9 +10,13 @@
 # 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
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+import apbs  # noqa: E402
+from datetime import date
 
 # Start TODO: This is part of issue https://github.com/Electrostatics/apbs/issues/41
 # Based on https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
@@ -30,15 +34,15 @@
 #     breathe_projects['src'] = output_dir + '/xml'
 # End TODO:
 
-
 # -- Project information -----------------------------------------------------
 
-project = 'APBS'
-copyright = '2021, Nathan Baker and many others'
-author = 'Nathan Baker and many others'
+project = "APBS"
+copyright = f"{date.today().year}, Nathan Baker and many others"
+
+author = "Nathan Baker and many others"
 
 # The full version, including alpha/beta/rc tags
-release = '3.2.0'
+release = apbs._version.__version__
 
 
 # -- General configuration ---------------------------------------------------
@@ -47,29 +51,34 @@ release = '3.2.0'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx.ext.autosummary',
-    'sphinx_rtd_theme', 'sphinx.ext.mathjax', 'sphinx_sitemap'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx_rtd_theme",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
 ]
 
-mathjax_path = 'https://cdnjs.cloudflare.com'
-mathjax_path += '/ajax/libs/mathjax/2.7.0/MathJax.js'
-mathjax_path += '?config=TeX-AMS-MML_HTMLorMML'
+mathjax_path = "https://cdnjs.cloudflare.com"
+mathjax_path += "/ajax/libs/mathjax/2.7.0/MathJax.js"
+mathjax_path += "?config=TeX-AMS-MML_HTMLorMML"
 site_url = "https://apbs.readthedocs.io"
 
 autosummary_generate = True
 autosummary_imported_members = False
 autosummary_generate_overwrite = True
 
-master_doc = 'index'
+master_doc = "index"
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -77,14 +86,14 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # 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 = "sphinx_rtd_theme"
 
 # 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"]
 
 # Enable intersphinx mapping
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
+    "python": ("https://docs.python.org/3", None),
 }

docs/conf.py.in

@@ -1,90 +0,0 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-# 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
-# sys.path.insert(0, os.path.abspath('.'))
-
-# Start TODO: This is part of issue https://github.com/Electrostatics/apbs/issues/41
-# Based on https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
-
-# import subprocess, os
-
-# # Check if we're running on Read the Docs' servers
-# read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
-
-# breathe_default_project = "src"
-# breathe_projects = {}
-
-# if read_the_docs_build:
-#     subprocess.call('doxygen', shell=True)
-#     breathe_projects['src'] = output_dir + '/xml'
-# End TODO:
-
-
-# -- Project information -----------------------------------------------------
-
-project = 'APBS'
-copyright = '__YEAR__, Nathan Baker and many others'
-author = 'Nathan Baker and many others'
-
-# The full version, including alpha/beta/rc tags
-release = '__PROJECT_VERSION__'
-
-
-# -- General configuration ---------------------------------------------------
-
-# 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.intersphinx', 'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx.ext.autosummary',
-    'sphinx_rtd_theme', 'sphinx.ext.mathjax', 'sphinx_sitemap'
-]
-
-mathjax_path = 'https://cdnjs.cloudflare.com'
-mathjax_path += '/ajax/libs/mathjax/2.7.0/MathJax.js'
-mathjax_path += '?config=TeX-AMS-MML_HTMLorMML'
-site_url = "https://apbs.readthedocs.io"
-
-autosummary_generate = True
-autosummary_imported_members = False
-autosummary_generate_overwrite = True
-
-master_doc = 'index'
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
-
-# -- 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'
-
-# 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']
-
-# Enable intersphinx mapping
-intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
-}

setup.py

@@ -1,16 +1,33 @@
 """Set up the APBS package."""
-import setuptools
+from sys import version_info
+from setuptools import find_packages, setup
 
+# NOTE: The following reads the version number and makes
+#       if available to the packaging tools before installation.
+#       REF: https://stackoverflow.com/questions/458550/standard-way-to-embed-version-into-python-package  # noqa: E501
+#       This makes __version__ valid below
+with open("apbs/_version.py") as fobj:
+    exec(fobj.read())
 
-setuptools.setup(
+# NOTE: The reason for version 3.7 vs. 3.8 is that ReadTheDocs
+#       is running version 3.7 so setting this to 3.8 causes
+#       the documentation build to fail.
+if version_info[:2] < (3, 7):
+    raise RuntimeError("Python version >= 3.7 is required.")
+
+with open("README.md", "r") as fobj:
+    LONG_DESCRIPTION = fobj.read()
+
+setup(
     name="apbs",
-    version="broken",
+    version=__version__,  # noqa: F821
     description="APBS biomolecular solvation software",
-    python_requires=">=3.8",
+    long_description=LONG_DESCRIPTION,
+    python_requires=">=3.7",
     author="Nathan Baker",
     author_email="nathanandrewbaker@gmail.com",
     url="https://www.poissonboltzmann.org",
-    packages=setuptools.find_packages(),
+    packages=find_packages(),
     package_data={"": ["*.yaml"]},
     install_requires=["numpy", "pyyaml"],
     tests_require=["pytest", "requests"],