From e025d5ffacc592f677c7c907c48969d0ae1c898b Mon Sep 17 00:00:00 2001 From: Will Handley Date: Mon, 26 Jun 2023 15:40:56 +0100 Subject: [PATCH] Packaging setup mark 1 (#1) * Added a gitignore file * Updated version number * Added docstring to __init__ * Added documentation * Added index.html * Reduced workflow --- .github/workflows/CI.yaml | 57 +-------- .gitignore | 10 ++ LICENSE | 2 +- README.rst | 20 ++- docs/Makefile | 19 +++ docs/make.bat | 35 +++++ docs/source/conf.py | 242 +++++++++++++++++++++++++++++++++++ docs/source/index.rst | 10 ++ docs/source/modules.rst | 7 + docs/source/unimpeded.rst | 10 ++ docs/templates/package.rst_t | 57 +++++++++ docs/templates/toc.rst_t | 8 ++ tests/test_example.py | 2 + unimpeded/__init__.py | 1 + unimpeded/_version.py | 2 +- 15 files changed, 419 insertions(+), 63 deletions(-) create mode 100644 .gitignore create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/modules.rst create mode 100644 docs/source/unimpeded.rst create mode 100644 docs/templates/package.rst_t create mode 100644 docs/templates/toc.rst_t create mode 100644 tests/test_example.py diff --git a/.github/workflows/CI.yaml b/.github/workflows/CI.yaml index 02dc8fb..35fb92c 100644 --- a/.github/workflows/CI.yaml +++ b/.github/workflows/CI.yaml @@ -52,71 +52,20 @@ jobs: make html SPHINXOPTS="-W --keep-going -n" pip: - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest] - python-version: ['3.8', '3.9', '3.10'] - extras: [true, false] - include: - - os: macos-latest - python-version: '3.10' - extras: true - - os: windows-latest - python-version: '3.10' - extras: true - + runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - name: Set up Python ${{ matrix.python-version }} + - name: Set up Python 3.8 uses: actions/setup-python@v4 with: - python-version: ${{ matrix.python-version }} + python-version: 3.8 - name: Install dependencies run: | python -m pip install --upgrade pip python -m pip install -e ".[test]" - - name: Install extra dependencies - if: ${{ matrix.extras }} - run: | - python -m pip install -e ".[all]" - - - name: Test with pytest - run: python -m pytest --cov=unimpeded tests - - - name: Upload coverage to Codecov - uses: codecov/codecov-action@v1 - - conda: - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest] - python-version: ['3.8', '3.9', '3.10'] - include: - - os: macos-latest - python-version: '3.10' - - os: windows-latest - python-version: '3.10' - - steps: - - uses: actions/checkout@v3 - - name: Set up Python ${{ matrix.python-version }} - uses: conda-incubator/setup-miniconda@v2 - with: - python-version: ${{ matrix.python-version }} - - - name: Install dependencies - shell: bash -l {0} - run: | - conda config --append channels conda-forge - conda install pytest pytest-cov - conda install scipy numpy 'matplotlib>=3.6.1' 'pandas>=2.0.0' - - name: Test with pytest - shell: bash -l {0} run: python -m pytest --cov=unimpeded tests - name: Upload coverage to Codecov diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d6b8409 --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +__pycache__ +*.pyc +.eggs +.ipynb_checkpoints +dist +*.egg-info/ +build +*~ +.pytest_cache/* +.coverage diff --git a/LICENSE b/LICENSE index 96f7ee1..d4e7aae 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2022 Will Handley +Copyright (c) 2023 Will Handley Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.rst b/README.rst index 8dfc07a..8834a13 100644 --- a/README.rst +++ b/README.rst @@ -1,9 +1,9 @@ -================================================================================== -unimpeded: Universal model comparison & parameter estimation over diverse datasets -================================================================================== -:unimpeded: Universal model comparison & parameter estimation over diverse datasets +=========================================================================================== +unimpeded: Universal model comparison & parameter estimation distributed over every dataset +=========================================================================================== +:unimpeded: Universal model comparison & parameter estimation distributed over every dataset :Author: Will Handley -:Version: 0.0.0 +:Version: 0.0.1 :Homepage: https://github.com/handley-lab/unimpeded :Documentation: http://unimpeded.readthedocs.io/ @@ -95,9 +95,15 @@ Full Documentation is hosted at `ReadTheDocs ` .. code:: bash - cd docs - make html + python -m pip install ".[all,docs]" + cd docs + make html +and view the documentation by opening ``docs/build/html/index.html`` in a browser. To regenerate the automatic RST files run: + +.. code:: bash + + sphinx-apidoc -fM -t docs/templates/ -o docs/source/ unimpeded/ Citation -------- diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..69fe55e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +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) \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..543c6b1 --- /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=source +set BUILDDIR=build + +if "%1" == "" goto help + +%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.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..b712a2b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,242 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +import sys +import os +sys.path.append(os.path.abspath('../../')) + +def get_version(short=False): + with open('../../README.rst') as f: + for line in f: + if ':Version:' in line: + ver = line.split(':')[2].strip() + if short: + subver = ver.split('.') + return '%s.%s' % tuple(subver[:2]) + else: + return ver + +# -- Project information ----------------------------------------------------- + +project = 'unimpeded' +copyright = '2023, Will Handley' +author = 'Will Handley and Lukas Hergt' + +# The short X.Y version +version = get_version(True) +# The full version, including alpha/beta/rc tags +release = get_version() + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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.autosummary', + 'sphinx.ext.autosectionlabel', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.mathjax', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages', + 'sphinx.ext.imgconverter', + 'matplotlib.sphinxext.plot_directive', + 'numpydoc', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# 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 = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for autodoc ------------------------------------------------- +autodoc_default_options = { + 'members': True, + 'undoc-members': True, +} + +autosummary_generate = True + +nitpick_ignore = [('py:obj', 'pandas.core.groupby.SeriesGroupBy.sample')] # not currently included in pandas 1.5, but will in future + +# -- Options for autosectionlabel------------------------------------------ +autosectionlabel_prefix_document = True + +# -- Options for numpydoc ------------------------------------------------- +numpydoc_show_inherited_class_members = False +numpydoc_show_class_members = False + + +# -- Options for matplotlib extension ---------------------------------------- + +plot_rcparams = {'savefig.bbox': 'tight'} +plot_apply_rcparams = True # if context option is used +plot_include_source = True +plot_html_show_source_link = False +plot_html_show_formats = False + + +# -- 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' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'unimpededdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'unimpeded.tex', 'unimpeded Documentation', + 'Will Handley', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'unimpeded', 'unimpeded Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'unimpeded', 'unimpeded Documentation', + author, 'unimpeded', 'Universal model comparison & parameter estimation distributed over every dataset.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + 'numpy':('https://numpy.org/doc/stable', None), + 'scipy':('https://docs.scipy.org/doc/scipy', None), + 'pandas':('https://pandas.pydata.org/pandas-docs/stable', None), + 'matplotlib':('https://matplotlib.org/stable', None), + 'getdist':('https://getdist.readthedocs.io/en/latest/', None) + } + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..aa9117e --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,10 @@ +.. title:: Introduction + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + anesthetic + +.. include:: ../../README.rst + diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..d0ed857 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +unimpeded +========= + +.. toctree:: + :maxdepth: 4 + + unimpeded diff --git a/docs/source/unimpeded.rst b/docs/source/unimpeded.rst new file mode 100644 index 0000000..6b2b111 --- /dev/null +++ b/docs/source/unimpeded.rst @@ -0,0 +1,10 @@ +unimpeded package +================= + +Module contents +--------------- + +.. automodule:: unimpeded + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/templates/package.rst_t b/docs/templates/package.rst_t new file mode 100644 index 0000000..979cfc1 --- /dev/null +++ b/docs/templates/package.rst_t @@ -0,0 +1,57 @@ +{%- macro automodule(modname, options) %} +.. automodule:: {{ modname }} +{%- for option in options %} + :{{ option }}: +{%- endfor %} +{%- endmacro %} + +{%- macro toctree(docnames, maxdepth=4) %} +.. toctree:: + :maxdepth: {{ maxdepth }} +{% for docname in docnames %} + {{ docname }} +{%- endfor %} +{% endmacro %} + +{%- if is_namespace %} +{{- [pkgname, "namespace"] | join(" ") | e | heading(1) }} +{%- else %} +{{- [pkgname, "package"] | join(" ") | e | heading(1) }} +{%- endif %} + +{%- if is_namespace %} +.. py:module:: {{ pkgname }} +{% endif %} + +{%- if modulefirst and not is_namespace %} +{{ automodule(pkgname, automodule_options) }} +{% endif %} + +{%- if subpackages %} +{{ [pkgname, "subpackages"] | join(" ") | e | heading(2) }} +{{ toctree(subpackages, 1) }} +{% if submodules %} +{{ [pkgname, "modules"] | join(" ") | e | heading(2) }} +{%- endif %} +{%- endif %} + +{%- if submodules %} +{%- if separatemodules %} +{{ toctree(submodules) }} +{%- else %} +{%- for submodule in submodules %} +{% if show_headings %} +{%- if subpackages %} +{{ [submodule, "module"] | join(" ") | e | heading(3) }} +{%- else %} +{{ [submodule, "module"] | join(" ") | e | heading(2) }} +{%- endif %} +{%- endif %} +{{ automodule(submodule, automodule_options) }} +{% endfor %} +{% endif %} +{% endif %} + +{%- if not modulefirst and not is_namespace %} +{{ automodule(pkgname, automodule_options) }} +{% endif %} diff --git a/docs/templates/toc.rst_t b/docs/templates/toc.rst_t new file mode 100644 index 0000000..f1190c2 --- /dev/null +++ b/docs/templates/toc.rst_t @@ -0,0 +1,8 @@ +{{ header | heading }} + +.. toctree:: + :maxdepth: 5 +{% for docname in docnames %} + {{ docname }} +{%- endfor %} + diff --git a/tests/test_example.py b/tests/test_example.py new file mode 100644 index 0000000..813df60 --- /dev/null +++ b/tests/test_example.py @@ -0,0 +1,2 @@ +def test_example(): + assert True diff --git a/unimpeded/__init__.py b/unimpeded/__init__.py index e69de29..c1b31a8 100644 --- a/unimpeded/__init__.py +++ b/unimpeded/__init__.py @@ -0,0 +1 @@ +"""unimpeded: Universal model comparison & parameter estimation.""" diff --git a/unimpeded/_version.py b/unimpeded/_version.py index c57bfd5..b8023d8 100644 --- a/unimpeded/_version.py +++ b/unimpeded/_version.py @@ -1 +1 @@ -__version__ = '0.0.0' +__version__ = '0.0.1'