Move documentation build scripts from mpi_cmake_modules to separate package

.gitignore

@@ -0,0 +1,3 @@
+build/
+venv/
+*.egg-info

CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+### Added
+- Try to auto-detect package version if not explicitly specified.
+- Install executable `bcat`.
+- Short arguments `-p`/`-o` for `--package-dir`/`--output-dir`.
+
+### Changed
+- Renamed `--project-version` to `--package-version`.
+
+### Fixed
+- Workaround for an incompatibility issue between the RTD theme and autodoc, which
+  caused class properties to be floating (see
+  https://github.com/readthedocs/sphinx_rtd_theme/issues/1247)
+
+## [0.1.0] - 2022-09-08
+Extracted the documentation build code from
+[mpi_cmake_modules](https://github.com/machines-in-motion/mpi_cmake_modules) with only
+some minor changes. 

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, New York University and Max Planck Gesellschaft.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,69 @@
+Documentation Builder for C++ and Python packages
+=================================================
+
+breathing_cat is a tool for building documentation that is used for some of the
+software packages developed at the Max Planck Institute for Intelligent Systems (MPI-IS)
+and the New York University.
+
+It is basically a wrapper around Doxygen, Sphinx and Breathe and runs those tools to
+generate a Sphinx-based documentation, automatically including API documentation for
+C++, Python and CMake code found in the package.
+
+It is tailored to work with the structure of our packages but we are doing nothing
+extraordinary there, so it will likely work for others as well (see below for the
+assumptions we make regarding the package structure).
+
+
+Installation
+------------
+
+Simply clone this repository and install it with
+
+```
+cd path/to/breathing-cat
+pip install .
+```
+
+Note that for building C++ API documentation Doxygen is used, which needs to be
+installed separately (e.g. with `sudo apt install doxygen` on Ubuntu).
+
+
+Usage
+-----
+
+In the most simple case you can run it like this:
+
+```
+bcat --package-dir path/to/package --output-dir path/to/output
+```
+
+If no package version is specified, `bcat` tries to find it by checking a
+number of files in the package directory.  If no version is found this way, it fails
+with an error.  In this case, you can explicitly specify the version using
+`--package-version`.
+
+`bcat` tries to automatically detect if the package contains Python code and,
+if yes, adds a Python API section to the documentation.  However, if your package
+contains Python modules that are only generated at build-time (e.g. Python bindings for
+C++ code) you can use `--python-dir` to specify the directory where the Python modules
+are installed to.  This way, the generated modules will be included in the documentation
+as well.
+
+For a complete list of options see `bcat --help`.
+
+Instead of the `bcat` executable, you can also use `python -m breathing_cat`.
+
+
+
+Assumptions Regarding Package Structure
+---------------------------------------
+
+TODO
+
+
+Copyright & License
+-------------------
+
+Copyright (c) 2022, New York University and Max Planck Gesellschaft.
+
+License: BSD 3-clause (see LICENSE).

breathing_cat/__init__.py

@@ -0,0 +1,3 @@
+import importlib.metadata
+
+__version__ = importlib.metadata.version(__package__)

breathing_cat/__main__.py

@@ -0,0 +1,97 @@
+import argparse
+import logging
+import pathlib
+import sys
+
+from . import __version__, find_version
+from .build import build_documentation
+
+
+def main():
+    def AbsolutePath(path):
+        return pathlib.Path(path).absolute()
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--version",
+        action="version",
+        help="Show version of breathing-cat.",
+        version=f"breathing-cat version {__version__}",
+    )
+    parser.add_argument(
+        "--output-dir",
+        "-o",
+        required=True,
+        type=AbsolutePath,
+        help="Build directory",
+    )
+    parser.add_argument(
+        "--package-dir",
+        "-p",
+        required=True,
+        type=AbsolutePath,
+        help="Package directory",
+    )
+    parser.add_argument(
+        "--python-dir",
+        type=AbsolutePath,
+        help="""Directory containing the Python package.  If not set, it is
+            auto-detected inside the package directory
+        """,
+    )
+    parser.add_argument(
+        "--package-version",
+        type=str,
+        help="""Package version that is shown in the documentation (something like
+            '1.42.0').  If not set, breathing-cat tries to auto-detect it by looking
+            for files like package.xml in the package directory.
+        """,
+    )
+    parser.add_argument(
+        "--force",
+        "-f",
+        action="store_true",
+        help="Do not ask before deleting files.",
+    )
+    parser.add_argument("--verbose", action="store_true", help="Enable debug output.")
+    args = parser.parse_args()
+
+    if args.verbose:
+        logger_level = logging.DEBUG
+    else:
+        logger_level = logging.INFO
+    logging.basicConfig(level=logger_level)
+
+    if not args.force and args.output_dir.exists():
+        print(
+            "Output directory {} already exists."
+            " It will be deleted if you proceed!".format(args.output_dir)
+        )
+        c = input("Continue? [y/N] ")
+
+        if c not in ["y", "Y", "yes"]:
+            print("Abort.")
+            return 1
+
+    if not args.package_version:
+        try:
+            args.package_version = find_version.find_version(args.package_dir)
+        except find_version.VersionNotFound:
+            print(
+                "ERROR: Package version could not be determined."
+                "  Please specify it using --package-version."
+            )
+            return 1
+
+    build_documentation(
+        args.output_dir,
+        args.package_dir,
+        args.package_version,
+        python_pkg_path=args.python_dir,
+    )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())