From caa496fa07e53a80f67a96df69f4d281489673da Mon Sep 17 00:00:00 2001 From: mjwen Date: Sun, 24 Dec 2023 21:53:08 -0600 Subject: [PATCH 1/6] Update .readthedocs.yaml --- .readthedocs.yaml | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 917aa8a4..430c3010 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,18 +4,24 @@ # Required version: 2 +# Set the version of Python 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/source/conf.py + configuration: docs/source/conf.py # Optionally build your docs in additional formats such as PDF formats: - - pdf + - pdf # Optionally set the version of Python and requirements required to build your docs python: - version: "3.10" - install: - - requirements: docs/requirements-docs.txt - - method: pip - path: . + version: "3.10" + install: + - requirements: docs/requirements-docs.txt + - method: pip + path: . From 137a7fc362fc6853fa1b657b08ce2009d7cacb63 Mon Sep 17 00:00:00 2001 From: mjwen Date: Sun, 24 Dec 2023 22:01:52 -0600 Subject: [PATCH 2/6] Add requirements-docs.txt --- .readthedocs.yaml | 3 --- docs/requirements-docs.txt | 5 +++++ 2 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 docs/requirements-docs.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 430c3010..fa46de50 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -20,8 +20,5 @@ formats: # Optionally set the version of Python and requirements required to build your docs python: - version: "3.10" install: - requirements: docs/requirements-docs.txt - - method: pip - path: . diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 00000000..214f788b --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,5 @@ +sphinx +furo +sphinx-gallery +sphinx-autodoc-typehints +matplotlib From 367899fd4f55025339cf90cbb93da1701997d4d5 Mon Sep 17 00:00:00 2001 From: mjwen Date: Sun, 24 Dec 2023 22:18:54 -0600 Subject: [PATCH 3/6] Move generate_api_docs.py out of conf.py --- devtool/README.md | 2 + docs/generate_api_docs.py | 102 ++++++++++++++++++++++++++++++++++++ docs/source/conf.py | 106 -------------------------------------- 3 files changed, 104 insertions(+), 106 deletions(-) create mode 100644 docs/generate_api_docs.py diff --git a/devtool/README.md b/devtool/README.md index b8f825b1..f82416ec 100644 --- a/devtool/README.md +++ b/devtool/README.md @@ -14,6 +14,8 @@ - Update docs at `kliff/docs/source` as necessary +- In docs, run `$ generate_api_docs.py` to generate API docs + - Generate docs by running `$ make html` in the `kliff/docs` directory - Note, check the generated tutorial notebooks -- sometimes sphinx-galley will diff --git a/docs/generate_api_docs.py b/docs/generate_api_docs.py new file mode 100644 index 00000000..ad0822fe --- /dev/null +++ b/docs/generate_api_docs.py @@ -0,0 +1,102 @@ +import subprocess +from pathlib import Path + + +def get_all_modules(source: Path = "./kliff") -> list[str]: + """ + Get all modules of the package. + + Note, this only get the first-level modules like `kliff.module_a`, not modules + (in subpackages) like `kliff.subpackage_a.module_b`. subpackage is considered + as a module. + + This takes advantage of + $ sphinx-apidoc -f -e -o + Return a list of modules names. + """ + results = subprocess.run( + ["sphinx-apidoc", "-f", "-e", "-o", "/tmp/kliff_apidoc", source], + capture_output=True, + ) + results = results.stdout.decode("utf-8") + + modules = [] + for line in results.split("\n"): + if "Creating" in line: + name = line.split("/")[-1].split(".") + if len(name) >= 4: + mod = name[1] + if mod not in modules: + modules.append(mod) + return modules + + +def autodoc_package(path: Path, modules: list[str]): + """ + Create a package reference page. + + Args: + path: directory to place the file + modules: list of API modules + """ + path = Path(path).resolve() + if not path.exists(): + path.mkdir(parents=True) + + with open(path / "kliff.rst", "w") as f: + f.write(".. _reference:\n\n") + f.write("Package Reference\n") + f.write("=================\n\n") + f.write(".. toctree::\n") + for m in modules: + f.write(" kliff." + m + "\n") + + +def autodoc_module(path: Path, module: str): + """ + Create a module reference page. + + Args: + path: directory to place the file + module: name of the module + """ + path = Path(path).resolve() + if not path.exists(): + path.mkdir(parents=True) + + module_name = "kliff." + module + fname = path.joinpath(module_name + ".rst") + with open(fname, "w") as f: + f.write(f"{module_name}\n") + f.write("-" * len(module_name) + "\n\n") + f.write(f".. automodule:: {module_name}\n") + f.write(" :members:\n") + f.write(" :undoc-members:\n") + # f.write(" :show-inheritance:\n") + f.write(" :inherited-members:\n") + + +def create_apidoc(directory: Path = "./apidoc"): + """ + Create API documentation, a separate page for each module. + + Args: + directory: + """ + + # modules with the below names will not be excluded + excludes = ["cmdline"] + + package_path = Path(__file__).parents[2] / "kliff" + modules = get_all_modules(package_path) + for exc in excludes: + modules.remove(exc) + modules = sorted(modules) + + autodoc_package(directory, modules) + for mod in modules: + autodoc_module(directory, mod) + + +if __name__ == "__main__": + create_apidoc(directory="./source/apidoc") diff --git a/docs/source/conf.py b/docs/source/conf.py index cecec37f..fecc8b30 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -12,8 +12,6 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. import os import sys -import subprocess -from pathlib import Path # sys.path.insert(0, os.path.abspath('.')) @@ -235,107 +233,3 @@ # -- myst-nb ----------------------------------------------------------------- nb_execution_timeout = 120 - -# -- generate api doc ---------------------------------------------------------- - - -def get_all_modules(source: Path = "./kliff") -> list[str]: - """ - Get all modules of the package. - - Note, this only get the first-level modules like `kliff.module_a`, not modules - (in subpackages) like `kliff.subpackage_a.module_b`. subpackage is considered - as a module. - - This takes advantage of - $ sphinx-apidoc -f -e -o - Return a list of modules names. - """ - results = subprocess.run( - ["sphinx-apidoc", "-f", "-e", "-o", "/tmp/kliff_apidoc", source], - capture_output=True, - ) - results = results.stdout.decode("utf-8") - - modules = [] - for line in results.split("\n"): - if "Creating" in line: - name = line.split("/")[-1].split(".") - if len(name) >= 4: - mod = name[1] - if mod not in modules: - modules.append(mod) - return modules - - -def autodoc_package(path: Path, modules: list[str]): - """ - Create a package reference page. - - Args: - path: directory to place the file - modules: list of API modules - """ - path = Path(path).resolve() - if not path.exists(): - path.mkdir(parents=True) - - with open(path / "kliff.rst", "w") as f: - f.write(".. _reference:\n\n") - f.write("Package Reference\n") - f.write("=================\n\n") - f.write(".. toctree::\n") - for m in modules: - f.write(" kliff." + m + "\n") - - -def autodoc_module(path: Path, module: str): - """ - Create a module reference page. - - Args: - path: directory to place the file - module: name of the module - """ - path = Path(path).resolve() - if not path.exists(): - path.mkdir(parents=True) - - module_name = "kliff." + module - fname = path.joinpath(module_name + ".rst") - with open(fname, "w") as f: - f.write(f"{module_name}\n") - f.write("-" * len(module_name) + "\n\n") - f.write(f".. automodule:: {module_name}\n") - f.write(" :members:\n") - f.write(" :undoc-members:\n") - # f.write(" :show-inheritance:\n") - f.write(" :inherited-members:\n") - - -def create_apidoc(directory: Path = "./apidoc"): - """ - Create API documentation, a separate page for each module. - - Args: - directory: - - Returns: - - """ - - # modules with the below names will not be excluded - excludes = ["cmdline"] - - package_path = Path(__file__).parents[2] / "kliff" - modules = get_all_modules(package_path) - for exc in excludes: - modules.remove(exc) - modules = sorted(modules) - - autodoc_package(directory, modules) - for mod in modules: - autodoc_module(directory, mod) - - -create_apidoc(directory="./apidoc") From a960a32b7d6f18e2abb52cd309df455cfad1606b Mon Sep 17 00:00:00 2001 From: mjwen Date: Sun, 24 Dec 2023 22:23:51 -0600 Subject: [PATCH 4/6] Add more docs depedency --- docs/requirements-docs.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index 214f788b..b2811bb8 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -3,3 +3,5 @@ furo sphinx-gallery sphinx-autodoc-typehints matplotlib +myst-nb +sphinx-copybutton \ No newline at end of file From be54de95705dbe5a931e67fbfb52c8ac5e9bfc5e Mon Sep 17 00:00:00 2001 From: mjwen Date: Sun, 24 Dec 2023 22:34:41 -0600 Subject: [PATCH 5/6] Fix version in changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f872a3b4..646b98c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Change Log -## v0.4.2 (2023/12/17) +## v0.4.3 (2023/12/17) - Fix installing ptemcee From ac584c2beba8aab9ae03c85dd134cbb2d19017bd Mon Sep 17 00:00:00 2001 From: mjwen Date: Sun, 24 Dec 2023 22:38:10 -0600 Subject: [PATCH 6/6] Fix docs title --- docs/source/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 6fe0ed1f..964b3120 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -7,8 +7,8 @@ Installation KLIFF can be installed via package managers (conda or pip) or from source. -Conda ------ +Installing KLIFF +================ This recommended way to install KLIFF is via conda. You can install it by: .. code-block:: bash