From 0f87535a7645992a122f728a345718c9661e3a4c Mon Sep 17 00:00:00 2001 From: Jakob Nybo Nissen Date: Mon, 28 Aug 2023 14:30:06 +0200 Subject: [PATCH 01/13] Add Sphinx template --- .gitignore | 6 ++++++ docs/Makefile | 20 ++++++++++++++++++++ docs/conf.py | 30 ++++++++++++++++++++++++++++++ docs/index.rst | 23 +++++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ 5 files changed, 114 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat diff --git a/.gitignore b/.gitignore index 69103ae..fecbf78 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,12 @@ build/ dist/ **.egg-info +# Sphinx documenter creates these +_build +_static +_templates +/docs/reference + # MacOS automatically creates these files .DS_Store diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..bc1d1ad --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,30 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'mockup' +copyright = '2023, Jakob Nybo Nissen' +author = 'Jakob Nybo Nissen' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ +"sphinx.ext.autodoc", +"sphinx.ext.autodoc.typehints", +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..28eeaf4 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,23 @@ +.. mockup documentation master file, created by + sphinx-quickstart on Mon Aug 28 14:09:15 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +The mockup package +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + reference/modules + +Mockup is a Python package with some simple example code. +To get started, explore the `mockup.Circle`_ class. + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd From cb41f23d7a060d26ebd70d5ecfcfdf35750e76ba Mon Sep 17 00:00:00 2001 From: Henry Date: Mon, 22 Jan 2024 22:09:13 +0100 Subject: [PATCH 02/13] :art: sphinx_book_theme --- docs/README.md | 28 ++++++++++++++++ docs/conf.py | 89 +++++++++++++++++++++++++++++++++++++++++++------- docs/make.bat | 35 -------------------- pyproject.toml | 13 ++++---- 4 files changed, 112 insertions(+), 53 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/make.bat diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..c3aa20a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,28 @@ +# Docs creation + +In order to build the docs you need to + + 1. install sphinx and additional support packages + 2. build the package reference files + 3. run sphinx to create a local html version + +The documentation is build using readthedocs automatically. + +```bash +pip install sphinx_book_theme +``` + +## Build docs using Sphinx command line tools + +Command to be run from `path/to/docs`, i.e. from within the `docs` package folder: + +Options: + - `--separate` to build separate pages for each (sub-)module + +```bash +# pwd: docs +# apidoc +sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../mockup +# build docs +sphinx-build -n -W --keep-going -b html ./ ./_build/ +``` \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index bc1d1ad..87cb0e8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,30 +1,97 @@ # Configuration file for the Sphinx documentation builder. # -# For the full list of built-in configuration values, see the documentation: +# 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 +from importlib import metadata + + # -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'mockup' -copyright = '2023, Jakob Nybo Nissen' -author = 'Jakob Nybo Nissen' +copyright = '2024, Jakob Nybo Nissen, Henry Webel' +author = 'Jakob Nybo Nissen, Henry Webel' +PACKAGE_VERSION = metadata.version("mockup") +version = PACKAGE_VERSION +release = PACKAGE_VERSION + # -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#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.autodoc.typehints", + 'sphinx.ext.autodoc', + 'sphinx.ext.autodoc.typehints', + 'sphinx.ext.viewcode', + # 'myst_nb', + 'sphinx.ext.napoleon', + # 'sphinx_new_tab_link', ] +# https://myst-nb.readthedocs.io/en/latest/computation/execute.html +nb_execution_mode = "auto" + +myst_enable_extensions = ["dollarmath", "amsmath"] + +# Plolty support through require javascript library +# https://myst-nb.readthedocs.io/en/latest/render/interactive.html#plotly +html_js_files = [ + "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"] + +# https://myst-nb.readthedocs.io/en/latest/configuration.html +# Execution +nb_execution_raise_on_error = True +# Rendering +nb_merge_streams = True + +# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +# 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 ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' -html_static_path = ['_static'] +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# See: +# https://github.com/executablebooks/MyST-NB/blob/master/docs/conf.py +# html_title = "" +html_theme = "sphinx_book_theme" +# html_logo = "_static/logo-wide.svg" +# html_favicon = "_static/logo-square.svg" +html_theme_options = { + "github_url": "https://github.com/RasmussenLab/python_package", + "repository_url": "https://github.com/RasmussenLab/python_package", + "repository_branch": "main", + "home_page_in_toc": True, + "path_to_docs": "docs", + "show_navbar_depth": 1, + "use_edit_page_button": True, + "use_repository_button": True, + "use_download_button": True, + "launch_buttons": { + "colab_url": "https://colab.research.google.com" + # "binderhub_url": "https://mybinder.org", + # "notebook_interface": "jupyterlab", + }, + "navigation_with_keys": False, +} + +# 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"] diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 32bb245..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/pyproject.toml b/pyproject.toml index 74d3014..5ed0735 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,9 +1,9 @@ [project] -name = "mockup" authors = [ - { name="Jakob Nybo Nissen", email="jakobnybonissen@gmail.com" }, + {name = "Jakob Nybo Nissen", email = "jakobnybonissen@gmail.com"}, ] description = "A small example package" +name = "mockup" # This means: Load the version from the package itself. # See the section below: [tools.setuptools.dynamic] dynamic = ["version"] @@ -12,15 +12,14 @@ readme = "README.md" requires-python = ">=3.11" # These are keywords classifiers = [ - "Programming Language :: Python :: 3", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent", + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", ] [project.urls] -"Homepage" = "https://github.com/RasmussenLab/python_package" "Bug Tracker" = "https://github.com/RasmussenLab/python_package/issues" - +"Homepage" = "https://github.com/RasmussenLab/python_package" [tool.setuptools.dynamic] version = {attr = "mockup.__version__"} From aaad89654271ac4c9636d7cfede720b4fcc91a87 Mon Sep 17 00:00:00 2001 From: Henry Date: Mon, 22 Jan 2024 22:11:42 +0100 Subject: [PATCH 03/13] :heavy_plus_sign: doc dependencies --- docs/README.md | 5 ++++- pyproject.toml | 9 +++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index c3aa20a..348c778 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,8 +8,11 @@ In order to build the docs you need to The documentation is build using readthedocs automatically. +Install the docs dependencies of the package (as speciefied in toml): + ```bash -pip install sphinx_book_theme +# in main folder +pip install .[docs] ``` ## Build docs using Sphinx command line tools diff --git a/pyproject.toml b/pyproject.toml index 5ed0735..d6ea8df 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -24,6 +24,15 @@ classifiers = [ [tool.setuptools.dynamic] version = {attr = "mockup.__version__"} +[project.optional-dependencies] +docs = [ + "sphinx", + "sphinx-book-theme", + "myst-nb", + "ipywidgets", + "sphinx-new-tab-link", +] + # Configure the Ruff linter: Ignore error number 501 [tool.ruff] ignore = ["E501"] From e38311df7cec63a32b80291e33e081e2abf20508 Mon Sep 17 00:00:00 2001 From: Henry Date: Mon, 22 Jan 2024 22:13:24 +0100 Subject: [PATCH 04/13] :sparkles: build api documentation on readthedocs --- docs/conf.py | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 87cb0e8..7795c04 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -95,3 +95,33 @@ # 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"] + + +# -- Setup for sphinx-apidoc ------------------------------------------------- + +# Read the Docs doesn't support running arbitrary commands like tox. +# sphinx-apidoc needs to be called manually if Sphinx is running there. +# https://github.com/readthedocs/readthedocs.org/issues/1139 + +if os.environ.get("READTHEDOCS") == "True": + from pathlib import Path + + PROJECT_ROOT = Path(__file__).parent.parent + PACKAGE_ROOT = PROJECT_ROOT / "src" / "mockup" + + def run_apidoc(_): + from sphinx.ext import apidoc + apidoc.main([ + "--force", + "--implicit-namespaces", + "--module-first", + "--separate", + "-o", + str(PROJECT_ROOT / "docs" / "reference"), + str(PACKAGE_ROOT), + str(PACKAGE_ROOT / "*.c"), + str(PACKAGE_ROOT / "*.so"), + ]) + + def setup(app): + app.connect('builder-inited', run_apidoc) From 47b4d4e36b3438cc4963f5b42c7645f3c0e008f4 Mon Sep 17 00:00:00 2001 From: Henry Date: Mon, 22 Jan 2024 22:31:24 +0100 Subject: [PATCH 05/13] :art: format with black --- docs/conf.py | 52 ++++++++++++++++++++++++++++------------------------ setup.py | 1 + 2 files changed, 29 insertions(+), 24 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 7795c04..365ec8a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,9 +16,9 @@ # -- Project information ----------------------------------------------------- -project = 'mockup' -copyright = '2024, Jakob Nybo Nissen, Henry Webel' -author = 'Jakob Nybo Nissen, Henry Webel' +project = "mockup" +copyright = "2024, Jakob Nybo Nissen, Henry Webel" +author = "Jakob Nybo Nissen, Henry Webel" PACKAGE_VERSION = metadata.version("mockup") version = PACKAGE_VERSION release = PACKAGE_VERSION @@ -30,12 +30,12 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autodoc.typehints', - 'sphinx.ext.viewcode', - # 'myst_nb', - 'sphinx.ext.napoleon', - # 'sphinx_new_tab_link', + "sphinx.ext.autodoc", + "sphinx.ext.autodoc.typehints", + "sphinx.ext.viewcode", + "myst_nb", + "sphinx.ext.napoleon", + "sphinx_new_tab_link", ] # https://myst-nb.readthedocs.io/en/latest/computation/execute.html @@ -46,7 +46,8 @@ # Plolty support through require javascript library # https://myst-nb.readthedocs.io/en/latest/render/interactive.html#plotly html_js_files = [ - "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"] + "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js" +] # https://myst-nb.readthedocs.io/en/latest/configuration.html # Execution @@ -55,12 +56,12 @@ nb_merge_streams = True # 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 ------------------------------------------------- @@ -111,17 +112,20 @@ def run_apidoc(_): from sphinx.ext import apidoc - apidoc.main([ - "--force", - "--implicit-namespaces", - "--module-first", - "--separate", - "-o", - str(PROJECT_ROOT / "docs" / "reference"), - str(PACKAGE_ROOT), - str(PACKAGE_ROOT / "*.c"), - str(PACKAGE_ROOT / "*.so"), - ]) + + apidoc.main( + [ + "--force", + "--implicit-namespaces", + "--module-first", + "--separate", + "-o", + str(PROJECT_ROOT / "docs" / "reference"), + str(PACKAGE_ROOT), + str(PACKAGE_ROOT / "*.c"), + str(PACKAGE_ROOT / "*.so"), + ] + ) def setup(app): - app.connect('builder-inited', run_apidoc) + app.connect("builder-inited", run_apidoc) diff --git a/setup.py b/setup.py index 8bf1ba9..6068493 100644 --- a/setup.py +++ b/setup.py @@ -1,2 +1,3 @@ from setuptools import setup + setup() From 322ed2a21433e4d114a4161c5457c6331bc1a056 Mon Sep 17 00:00:00 2001 From: Henry Date: Mon, 5 Feb 2024 11:25:07 +0100 Subject: [PATCH 06/13] :sparkles: Add intersphinx and a tutorial --- docs/conf.py | 11 +++++- docs/index.rst | 19 ++++++++- docs/tutorial/tutorial.ipynb | 74 ++++++++++++++++++++++++++++++++++++ 3 files changed, 101 insertions(+), 3 deletions(-) create mode 100644 docs/tutorial/tutorial.ipynb diff --git a/docs/conf.py b/docs/conf.py index 365ec8a..eac69ce 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,9 +33,10 @@ "sphinx.ext.autodoc", "sphinx.ext.autodoc.typehints", "sphinx.ext.viewcode", - "myst_nb", "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", "sphinx_new_tab_link", + "myst_nb", ] # https://myst-nb.readthedocs.io/en/latest/computation/execute.html @@ -64,6 +65,14 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +# Intersphinx options +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + # "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), + # "scikit-learn": ("https://scikit-learn.org/stable/", None), + # "matplotlib": ("https://matplotlib.org/stable/", None), +} + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/index.rst b/docs/index.rst index 28eeaf4..46271ea 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,14 +6,29 @@ The mockup package ================================== +Mockup is a Python package with some simple example code. +To get started, explore the `mockup.Circle` class. + + +.. toctree:: + :maxdepth: 2 + :caption: Tutorial + + tutorial/tutorial + .. toctree:: :maxdepth: 2 :caption: Contents: reference/modules -Mockup is a Python package with some simple example code. -To get started, explore the `mockup.Circle`_ class. +.. toctree:: + :hidden: + :caption: Technical notes + + README.md + + Indices and tables ================== diff --git a/docs/tutorial/tutorial.ipynb b/docs/tutorial/tutorial.ipynb new file mode 100644 index 0000000..2cca348 --- /dev/null +++ b/docs/tutorial/tutorial.ipynb @@ -0,0 +1,74 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Mockup tutorial" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from mockup import mockup" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "mockup.add_one(-11)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "list(mockup.flatten_ints([[9, 11], [12], [4, 5]]))" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "c2 = mockup.Circle.from_circumference(100)\n", + "round(c2.radius, 3)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "pathways", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.4" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} From e49bd3fdee795e473e36ade3ebef1506c18611ee Mon Sep 17 00:00:00 2001 From: Henry Date: Mon, 5 Feb 2024 11:33:30 +0100 Subject: [PATCH 07/13] :art: set link to class on landing page --- docs/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 46271ea..7fac169 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,7 +7,8 @@ The mockup package ================================== Mockup is a Python package with some simple example code. -To get started, explore the `mockup.Circle` class. +To get started, explore the :class:`mockup.Circle` class. + .. toctree:: From ef6a336c5e4f675852e8d6d97e3096199b41ad34 Mon Sep 17 00:00:00 2001 From: Henry Date: Sat, 24 Feb 2024 18:35:42 +0100 Subject: [PATCH 08/13] :art: make package an implicit namespace --- docs/README.md | 2 +- {mockup => src/mockup}/__init__.py | 0 {mockup => src/mockup}/mockup.py | 0 3 files changed, 1 insertion(+), 1 deletion(-) rename {mockup => src/mockup}/__init__.py (100%) rename {mockup => src/mockup}/mockup.py (100%) diff --git a/docs/README.md b/docs/README.md index 348c778..cbce8fe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,7 +25,7 @@ Options: ```bash # pwd: docs # apidoc -sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../mockup +sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/mockup # build docs sphinx-build -n -W --keep-going -b html ./ ./_build/ ``` \ No newline at end of file diff --git a/mockup/__init__.py b/src/mockup/__init__.py similarity index 100% rename from mockup/__init__.py rename to src/mockup/__init__.py diff --git a/mockup/mockup.py b/src/mockup/mockup.py similarity index 100% rename from mockup/mockup.py rename to src/mockup/mockup.py From b574e7f7fa8104a728a686c8669d566b2631ed5b Mon Sep 17 00:00:00 2001 From: Henry Date: Sat, 24 Feb 2024 18:36:20 +0100 Subject: [PATCH 09/13] :art: add repr to class --- docs/tutorial/tutorial.ipynb | 9 +++++++++ src/mockup/mockup.py | 3 +++ 2 files changed, 12 insertions(+) diff --git a/docs/tutorial/tutorial.ipynb b/docs/tutorial/tutorial.ipynb index 2cca348..2cb608a 100644 --- a/docs/tutorial/tutorial.ipynb +++ b/docs/tutorial/tutorial.ipynb @@ -44,6 +44,15 @@ "round(c2.radius, 3)" ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "c2 # repr" + ] + }, { "cell_type": "markdown", "metadata": {}, diff --git a/src/mockup/mockup.py b/src/mockup/mockup.py index f92d591..58f2bcb 100644 --- a/src/mockup/mockup.py +++ b/src/mockup/mockup.py @@ -92,3 +92,6 @@ def diameter(self): @classmethod def from_circumference(cls, circumference: Union[int, float]) -> Self: return cls(circumference / (2 * cls.PI)) + + def __repr__(self): + return f"Circle({self.radius})" From 4b7dc984798b401c51427f8dffb40a1cefa889b1 Mon Sep 17 00:00:00 2001 From: Henry Date: Sat, 24 Feb 2024 18:38:20 +0100 Subject: [PATCH 10/13] :art: prepare uploading to test-PyPI - package name needs to be unique --- docs/conf.py | 2 +- pyproject.toml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index eac69ce..2bf9101 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,7 +19,7 @@ project = "mockup" copyright = "2024, Jakob Nybo Nissen, Henry Webel" author = "Jakob Nybo Nissen, Henry Webel" -PACKAGE_VERSION = metadata.version("mockup") +PACKAGE_VERSION = metadata.version("rasmussenlab-mockup") version = PACKAGE_VERSION release = PACKAGE_VERSION diff --git a/pyproject.toml b/pyproject.toml index d6ea8df..7c7d286 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ authors = [ {name = "Jakob Nybo Nissen", email = "jakobnybonissen@gmail.com"}, ] description = "A small example package" -name = "mockup" +name = "rasmussenlab-mockup" # This means: Load the version from the package itself. # See the section below: [tools.setuptools.dynamic] dynamic = ["version"] @@ -30,7 +30,7 @@ docs = [ "sphinx-book-theme", "myst-nb", "ipywidgets", - "sphinx-new-tab-link", + "sphinx-new-tab-link!=0.2.2", ] # Configure the Ruff linter: Ignore error number 501 From 00598f1141a575e1f99821ee3dbca51f89aceb70 Mon Sep 17 00:00:00 2001 From: Henry Date: Sun, 25 Feb 2024 10:13:21 +0100 Subject: [PATCH 11/13] :sparkles: PyPI uploaded manually - automatic detection using tag does not work yet --- README.md | 9 +++++++++ src/mockup/__init__.py | 5 ++++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 00ed322..b1a732f 100644 --- a/README.md +++ b/README.md @@ -8,3 +8,12 @@ Install package so that new code is picked up in a restared python interpreter: pip install -e . ``` +## TestPyPI + +Install vom [TestPyPI](https://test.pypi.org/project/rasmussenlab-mockup): + +``` +pip install -i https://test.pypi.org/simple/ rasmussenlab-mockup +``` + +> The package on PyPI is call `rasmussenlab-mockup` and not `mockup` as the package name is already taken. The import is still `import mockup`. \ No newline at end of file diff --git a/src/mockup/__init__.py b/src/mockup/__init__.py index 392eb9a..ef989e0 100644 --- a/src/mockup/__init__.py +++ b/src/mockup/__init__.py @@ -1,7 +1,10 @@ # The __init__.py file is loaded when the package is loaded. # It is used to indicate that the directory in which it resides is a Python package -__version__ = (0, 1, 0) +# ! does not work yet: +# from importlib import metadata +# __version__ = metadata.version("mockup") +__version__ = "24.02" from .mockup import add_one, Circle From 9a60f9a27b7b5e847193af47894ba2cb90883197 Mon Sep 17 00:00:00 2001 From: Henry Date: Sun, 25 Feb 2024 11:11:52 +0100 Subject: [PATCH 12/13] :sparkles: Readthedocs configuration --- .readthedocs.yaml | 35 +++++++++++++++++++++++++++++++++++ README.md | 10 +++++++++- 2 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..75f0fc0 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,35 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - method: pip + path: . + extra_requirements: + - docs diff --git a/README.md b/README.md index b1a732f..e7488a2 100644 --- a/README.md +++ b/README.md @@ -16,4 +16,12 @@ Install vom [TestPyPI](https://test.pypi.org/project/rasmussenlab-mockup): pip install -i https://test.pypi.org/simple/ rasmussenlab-mockup ``` -> The package on PyPI is call `rasmussenlab-mockup` and not `mockup` as the package name is already taken. The import is still `import mockup`. \ No newline at end of file +> The package on PyPI is call `rasmussenlab-mockup` and not `mockup` as the package name is already taken. The import is still `import mockup`. + +## Readthedocs + +The documentation is build using readthedocs automatically. See +[project on Readthedocs](https://readthedocs.org/projects/rasmussenlab-python-package/). + +- make sure to enable build from PRs in the settings (advanded settings) +- checkout configuration file: [`.readthedocs.yaml`](.readthedocs.yaml) \ No newline at end of file From 1122dc8df5b8f72f528f0857b0cc9548cb36239b Mon Sep 17 00:00:00 2001 From: Henry Date: Sun, 25 Feb 2024 11:47:14 +0100 Subject: [PATCH 13/13] :sparkles: setuptools_scm pick up version from tags and commits - see https://setuptools-scm.readthedocs.io/ - dynamic attribute picking --- pyproject.toml | 10 ++++++++-- src/mockup/__init__.py | 7 +++---- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 7c7d286..9639479 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,8 +21,6 @@ classifiers = [ "Bug Tracker" = "https://github.com/RasmussenLab/python_package/issues" "Homepage" = "https://github.com/RasmussenLab/python_package" -[tool.setuptools.dynamic] -version = {attr = "mockup.__version__"} [project.optional-dependencies] docs = [ @@ -36,3 +34,11 @@ docs = [ # Configure the Ruff linter: Ignore error number 501 [tool.ruff] ignore = ["E501"] + +[build-system] +build-backend = "setuptools.build_meta" +requires = ["setuptools>=64", "setuptools_scm>=8"] + +[tool.setuptools_scm] +# https://setuptools-scm.readthedocs.io/ +# used to pick up the version from the git tags or the latest commit. diff --git a/src/mockup/__init__.py b/src/mockup/__init__.py index ef989e0..d517e4a 100644 --- a/src/mockup/__init__.py +++ b/src/mockup/__init__.py @@ -1,10 +1,9 @@ # The __init__.py file is loaded when the package is loaded. # It is used to indicate that the directory in which it resides is a Python package -# ! does not work yet: -# from importlib import metadata -# __version__ = metadata.version("mockup") -__version__ = "24.02" + +from importlib import metadata +__version__ = metadata.version("rasmussenlab-mockup") from .mockup import add_one, Circle