maint: adopt pyproject.toml for build and drop setup.py

We had half of package information in pyproject.toml duplicated from
setup.py.  We were only using pyproject.toml to configure external
tools and left the build to setup.py.  We really needed setup.py
because it handled the call of sphinx-apidoc before sphinx-build and
our manual injection of extra files in source distribution.

This commit replaces our hack to insert files into source
distributions with using `MANIFEST.in` file.  It replaces our call of
sphinx-apidoc with the sphinx apidoc extension (configuration in
doc/conf.py).  So we no longer need a special setup.py and so we
replace it with a more extensive pyproject.toml.

Documentation on how to build documentation and prepare releases is
updated accordingly.

Author: David Miguel Susano Pinto

MANIFEST.in

@@ -0,0 +1,20 @@
+# We list here all extra non-standard files to be included in source
+# distributions.  We list *all*, even those that setuptools picks up
+# automatically --- at the moment setuptools picks up COPYING and
+# README.rst and ignores NEWS.rst and INSTALL.rst.  We list them all
+# because 1) we never know when setuptools changes their mind on what
+# files to include by default; 2) we may accidentally use an older
+# version of setuptools; or 3) we may move away from setuptools to
+# another build tool.
+#
+# Note we do not use package_data from setuptools.  That is for files
+# that will be included in the binary distribution, i.e., needed at
+# runtime.  We only want these files in the source distribution, they
+# are for user information.
+
+include COPYING
+include NEWS.rst
+include README.rst
+include INSTALL.rst
+
+graft doc

doc/conf.py

@@ -14,7 +14,7 @@
 import unittest.mock
 
 
-sys.path.insert(0, "../microscope")
+sys.path.insert(0, "..")
 
 
 # autodoc imports the modules to be documented.  Modules that wrap the
@@ -93,6 +93,7 @@ def sizeof_diversion(struct):
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "sphinxcontrib.apidoc",
 ]
 
 # Configuration for sphinx.ext.autodoc
@@ -125,6 +126,27 @@ def sizeof_diversion(struct):
 # Configuration for sphinx.ext.todo
 todo_include_todos = True
 
+# Configuration for sphinxcontrib.apidoc
+apidoc_module_dir = '../microscope'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = [
+    # Exclude the testsuite
+    "microscope/testsuite/",
+    # Exclude the wrappers to shared libraries
+    "microscope/_wrappers/",
+    # Exclude the deprecated devices and deviceserver that are kept
+    # for backwards compatibility only
+    "microscope/devices.py",
+    "microscope/deviceserver.py",
+    "microscope/lasers/",
+    # Exclude these that should be moved to microscope/_wrappers
+    "microscope/cameras/_SDK3.py",
+    "microscope/cameras/_SDK3Cam.py",
+]
+apidoc_separate_modules = True
+apidoc_toc_file = "index"
+apidoc_module_first = True
+apidoc_exra_args = ["--private"]
 
 #
 # Options for HTML output
@@ -145,3 +167,14 @@ def sizeof_diversion(struct):
 .. _gpl-licence: https://www.gnu.org/licenses/gpl-3.0.html
 .. _cockpit-link: https://github.com/MicronOxford/cockpit/
 """
+
+
+#
+# Options for LaTeX/PDF output
+#
+# Currently this has issues because of Japanese characters in
+# authors.rst.  But maybe it would make sense to change authors.rst or
+# maybe there's something smart we can do on LaTeX customisation with
+# latex_elements https://www.sphinx-doc.org/en/master/latex.html
+
+latex_show_urls = "footnote"

doc/get-involved/maintaining.rst

@@ -29,59 +29,72 @@ relevant change should also add the entry to the NEWS file.
 Steps to make a release
 =======================
 
-Because the ``NEWS`` file is supposed to always be kept up to date,
-there should be no need to check it.
-
-#. Change version number on ``setup.py`` and date on ``NEWS``.  Commit
-   these changes only.  Note that we use ``release-N`` for tag and not
-   ``v.N``.  This will enable us to one day perform snapshot releases
-   with tags such as ``snapshot-N``::
-
-    VERSION=$(python3 setup.py --version)
-    sed -i "s,(upcoming),($(date +%Y/%m/%d))," NEWS.rst
-    git commit -m "maint: release $VERSION" setup.py NEWS.rst
-    COMMIT=$(git rev-parse HEAD | cut -c1-12)
-    git tag -s -u $GPGKEY \
-      -m "Added tag release-$VERSION for commit $COMMIT" release-$VERSION
-
-#. Build a source distribution from a git archive export.  Performing
-   a release from a git archive will ensure that the release will not
-   accidentally include modified or untracked files::
-
-    rm -rf target/
-    git archive --format=tar --prefix="target/" HEAD | tar -x
-    cd target/
-    python3 setup.py sdist --formats=gztar
+#. Check the ``NEWS`` is up to date for the next release.  Because the
+   ``NEWS`` file is supposed to be kept up to date with each commit
+   that introduces changes worth mentioning, there should be no need
+   to add entries now.  But if so, then::
+
+    git commit -m "maint: update NEWS for upcoming release" NEWS.rst
+
+#. Manually add date and version for next release on ``NEWS.rst``.
+   Then change the version on ``pyproject.toml``, commit it, and tag
+   it::
+
+       NEW_VERSION="X.Y.Z"  # replace this with new version number
+       OLD_VERSION=`grep '^version ' pyproject.toml | sed 's,^version = "\([0-9.]*+dev\)"$,\1,'`
+       python3 -c "from packaging.version import parse; assert parse('$NEW_VERSION') > parse('$OLD_VERSION');"
+
+       sed -i 's,^version = "'$OLD_VERSION'"$,version = "'$NEW_VERSION'",' pyproject.toml
+       git commit -m "maint: release $NEW_VERSION" pyproject.toml NEWS.rst
+       COMMIT=$(git rev-parse HEAD | cut -c1-12)
+       git tag -a -m "Added tag release-$NEW_VERSION for commit $COMMIT" release-$NEW_VERSION
+
+   Note that we use ``release-N`` for tag and not ``v.N``.  This will
+   enable us to one day perform snapshot releases with tags such as
+   ``snapshot-N``.
+
+#. Build a source and wheel distribution from a git archive export::
+
+       rm -rf target
+       git archive --format=tar --prefix="target/" release-$NEW_VERSION | tar -x
+       (cd target/ ; python3 -m build)
+
+   Performing a release from a git archive ensures that the release
+   does not accidentally include modified or untracked files.  The
+   wheel distribution is not for actual distribution, we only build it
+   to ensure that a binary distribution can be built from the source
+   distribution.
 
    We should probably do this from a git clone and not an archive to
    ensure that we are not using a commit that has not been pushed yet.
 
-#. Upload and sign distribution::
+#. Upload source distribution to PyPI::
 
-    twine upload -r pypi -s -i $GPGKEY target/dist/microscope-X.tar.gz
+    twine upload -r pypi target/dist/microscope-$NEW_VERSION.tar.gz
 
-#. Add ``+dev`` to version string and a new entry on the ``NEWS``
-   file::
+#. Add ``+dev`` to version string and manually add a new entry on the
+   ``NEWS`` file for the upcoming version::
 
-    sed -i "s,\(^project_version = '[^+]*\)',\1+dev'," setup.py
-    # manually add new version line on NEWS file
-    git commit setup.py NEWS \
-      -m "maint: set version to $VERSION+dev after $VERSION release."
-    git push upstream master
-    git push upstream release-$VERSION
+       sed -i 's,^version = "'$NEW_VERSION'"$,version = "'$NEW_VERSION'+dev",' pyproject.toml
+       # manually add new version line on NEWS.rst file
+       git commit -m "maint: set version to $NEW_VERSION+dev after $NEW_VERSION release." pyproject.toml NEWS.rst
+       git push upstream master
+       git push upstream release-$NEW_VERSION
 
 
 Documentation
 =============
 
-The documentation is generated automatically with `sphinx
-<https://www.sphinx-doc.org/en/master/>`_.  The API section is
-generated from the inline docstrings and makes use of `Sphinx's
-Napoleon extension
-<http://www.sphinx-doc.org/en/stable/ext/napoleon.html>`_.  It is
-generated with::
+The documentation is generated with `Sphinx
+<https://www.sphinx-doc.org/>`__, like so::
+
+    sphinx-build -b html doc/ dist/sphinx/html
+    sphinx-build -M pdflatex doc/ dist/sphinx/pdf
 
-    python3 setup.py build_sphinx
+The API section is generated from the inline docstrings and makes use
+of Sphinx's `Napoleon
+<http://www.sphinx-doc.org/en/stable/ext/napoleon.html>`__ and `apidoc
+<https://github.com/sphinx-contrib/apidoc>`__ extensions.
 
 
 Versioning

pyproject.toml

@@ -1,29 +1,78 @@
+[project]
+name = "microscope"
+version = "0.7.0+dev"
+description = "An interface for control of microscope devices"
+readme = "README.rst"
+license = {file = "COPYING"}
+
+# Names are in alphabetical order.  This is the list of active
+# maintainers.  For the full list of people that have contributed to
+# the development of the project, see `doc/authors.rst`.
+maintainers = [
+    {name = "David Miguel Susano Pinto"},
+    {name = "Ian Dobbie"},
+    {name = "Julio Mateos-Langerak"},
+]
+
+# https://pypi.org/classifiers
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Topic :: Scientific/Engineering",
+]
+
+requires-python = ">=3.7"
+dependencies = [
+    "Pillow",
+    "Pyro4",
+    "hidapi",
+    "numpy",
+    "pyserial",
+    "scipy",
+]
+
+[project.optional-dependencies]
+GUI = ["PySide2"]
+
+[project.scripts]
+device-server = "microscope.device_server:_setuptools_entry_point"
+deviceserver = "microscope.device_server:_setuptools_entry_point"
+
+[project.gui-scripts]
+microscope-gui = "microscope.gui:_setuptools_entry_point [GUI]"
+
+[project.urls]
+Homepage = "https://www.python-microscope.org"
+Download = "https://pypi.org/project/microscope/"
+Documentation = "https://www.python-microscope.org/doc/"
+News = "https://www.python-microscope.org/doc/news.html"
+Source = "https://github.com/python-microscope/microscope"
+Tracker = "https://github.com/python-microscope/microscope"
+
+
 [build-system]
-requires = ['setuptools']
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-dir]
+microscope = "microscope"
 
 
 [tool.isort]
 profile = "black"
 line_length = 79
-lines_after_imports = 2
-# Despite the profile option being set to "black", there's still some
-# options that are not correcly set in a compatible manner.  The
-# following are for compatibility with black style.
-combine_as_imports = true
-include_trailing_comma = true
-multi_line_output = 3  # multi lineoutput 3 is vert-hanging
+
 
 [tool.black]
 line-length = 79
-target-version = ['py37', 'py38']
 
 
 [tool.pylint.FORMAT]
 max-line-length = 79
 
 
 [tool.pytest.ini_options]
-testpaths = "microscope/testsuite"
+testpaths = ["microscope/testsuite",]
 # python_classes must be an empty string otherwise it defaults to all
 # Test* classes which then include the TestDevices imported in the
 # test_* modules.  By using an empty value, it defaults to only
@@ -36,10 +85,15 @@ python_classes = ""
 [tool.tox]
 legacy_tox_ini = """
 [tox]
+# We need to set isolated_build because: 'pyproject.toml file found.
+# To use a PEP 517 build-backend you are required to configure tox to
+# use an isolated_build"
+isolated_build = True
 envlist = py
+
 [testenv]
 description = run whole test suite
 commands = python -m unittest discover \
-  --start-directory microscope/testsuite \
-  --verbose
+    --start-directory microscope/testsuite \
+    --verbose
 """