diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f26f4bb..497ba65 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -8,14 +8,14 @@ on: jobs: check-manifest: - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: - python-version: "3.10" + python-version: "3.12" - uses: pre-commit/action@v3.0.1 with: @@ -24,7 +24,7 @@ jobs: build-package: needs: check-manifest name: Build package - runs-on: ubuntu-latest + runs-on: ubuntu-22.04 steps: - name: Checkout @@ -53,7 +53,7 @@ jobs: strategy: fail-fast: false matrix: - os: [ubuntu-20.04, macOS-14, windows-2022] + os: [ubuntu-22.04, macOS-14, windows-2022] python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"] steps: @@ -97,7 +97,7 @@ jobs: upload-wheels: name: Upload wheels to PyPI needs: test-wheels - runs-on: ubuntu-latest + runs-on: ubuntu-22.04 steps: - uses: actions/download-artifact@v4 diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md new file mode 100644 index 0000000..8972244 --- /dev/null +++ b/CONTRIBUTORS.md @@ -0,0 +1,18 @@ +# Contributors + + +[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg)](#contributors) + + +This project welcomes contributions of all kinds and follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification to recognize them. + +Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): + + + + + + + + + diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..92dd33a --- /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 = 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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..b344c6a --- /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 + +%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/docs/source/_static/class.rst b/docs/source/_static/class.rst new file mode 100644 index 0000000..17d61dc --- /dev/null +++ b/docs/source/_static/class.rst @@ -0,0 +1,10 @@ +{{objname}} +{{ underline }}============== + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + +.. raw:: html + +
diff --git a/docs/source/_static/class_with_call.rst b/docs/source/_static/class_with_call.rst new file mode 100644 index 0000000..5b25f27 --- /dev/null +++ b/docs/source/_static/class_with_call.rst @@ -0,0 +1,11 @@ +{{objname}} +{{ underline }}=============== + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :special-members: __call__ + +.. raw:: html + +
diff --git a/docs/source/_static/function.rst b/docs/source/_static/function.rst new file mode 100644 index 0000000..54226b7 --- /dev/null +++ b/docs/source/_static/function.rst @@ -0,0 +1,10 @@ +{{objname}} +{{ underline }}==================== + +.. currentmodule:: {{ module }} + +.. autofunction:: {{ objname }} + +.. raw:: html + +
diff --git a/docs/source/_static/switcher.json b/docs/source/_static/switcher.json new file mode 100644 index 0000000..70582e0 --- /dev/null +++ b/docs/source/_static/switcher.json @@ -0,0 +1,12 @@ +[ + { + "name": "dev", + "version": "latest", + "url": "https://predictably.readthedocs.io/en/latest/" + }, + { + "name": "0.2.0 (stable)", + "version": "stable", + "url": "https://predictably.readthedocs.io/en/v0.2.0/" + } +] diff --git a/docs/source/about.rst b/docs/source/about.rst new file mode 100644 index 0000000..833c73d --- /dev/null +++ b/docs/source/about.rst @@ -0,0 +1,47 @@ +.. _top_level_about: + +===== +About +===== + +Learn more about the ``predictably_core`` project and its community. + +.. toctree:: + :maxdepth: 1 + :hidden: + + about/overview + about/contributors + about/governance + about/roadmap + +.. grid:: 1 2 2 2 + :gutter: 3 + + .. grid-item-card:: Overview + :text-align: left + :link: about/overview + :link-type: doc + + Learn more about ``predictably_core``. + + .. grid-item-card:: Contributors + :text-align: left + :link: about/contributors + :link-type: doc + + All of ``predictably_core``'s contributors. + + .. grid-item-card:: Governance + :text-align: left + :link: about/governance + :link-type: doc + + How we govern the project. + + .. grid-item-card:: Roadmap + :text-align: left + :link: about/roadmap + :link-type: doc + + Where we plan to take ``predictably_core``. diff --git a/docs/source/about/contributors.md b/docs/source/about/contributors.md new file mode 100644 index 0000000..362e062 --- /dev/null +++ b/docs/source/about/contributors.md @@ -0,0 +1,2 @@ +```{include} ../../../CONTRIBUTORS.md +``` diff --git a/docs/source/about/governance.rst b/docs/source/about/governance.rst new file mode 100644 index 0000000..9c172c9 --- /dev/null +++ b/docs/source/about/governance.rst @@ -0,0 +1,242 @@ +.. _governance: + +========== +Governance +========== + +Overview +======== + +``predictably_core`` is a consensus-based project that is part of the ``predictably`` +community. Anyone with an interest in the project can join the community, contribute +to the project, and participate in the governance process. The information below +explains the different roles in the community and how those roles work together +to make decisions. + +.. _gov_coc: + +Code of Conduct +=============== + +Contributors are expected to follow the ``predictably_core`` code of conduct. +The ``predictably_core`` project believes that everyone should be able to participate +in our community without fear of intimidation, bullying, harassment or discrimination. +All contributors are expected to show respect and courtesy to other members of +the community at all times. + +While contributing to the project, we recognize that there will be times that +individuals don't agree. Disagreement is *understandable*, particularly when +working on projects with people from different backgrounds. What's important is that +we still treat each other with respect and courtesy when we don't agree. + +It is also important to recognize that our different backgrounds provide different +viewpoints, and also impact how we interact and communicate with others. This +can lead to a disconnect between the intentions of those we interact with and how +the interaction feels to us. As always, respectful communication is key and it +is often possible to work together to overcome different communication styles. + +But when that's not possible or an interaction is based on intimidation, bullying, +harassment, or discrimination, you should report a Code of Conduct incident +by reaching out to predictably.ai@gmail.com. + +Roles +===== + +There are 3 roles in ``predictably_core`` community: + +- :ref:`Contributors ` +- :ref:`Core developers ` +- :ref:`Steering Committee Members ` + +.. _contribs: + +Contributors +------------ + +Anyone is welcome to contribute to the project. Contributions can take many +forms (not only code) as detailed in the :ref:`contributing guide ` + +For more details on how we acknowledge contributions, +see the :ref:`acknowledging contributions ` section below. + +All of our contributors are listed under the `contributors `_ +section of our documentation. + +.. _core-devs: + +Core developers +--------------- + +The :ref:`core developmer team ` helps manage the project by: + +- engaging with the contributor community +- managing issues and Pull Requests +- reviewing others contributions in accordance with the project + :ref:`reviewers guide ` +- approving and merging Pull Requests +- participating in the project's :ref:`roadmap` and decision making process +- nominating new core developers and steering committee members + +Any core developer nominee must receive affirmative votes from two-thirds of +existing core developers over the course of a one week voting period. + +Core developers can remain in their role for as long as they like as long as they +continue to perform the role's duties. Core developers who no longer want to +perform the role's duties can resign at any time, while core developers that become +inactive for a 12-month period will move to a "former" core developer status. +Core developers are expected promote a collaborative and inclusive environment +when working on the project; core developers who fail to live up to this standard +can also be removed by a 60% vote of the :ref:`steering committee `. + +.. _steering_committee: + +Steering Committee +------------------ + +Steering Committee (SC) :ref:`team members ` are core developers with +additional rights and responsibilities for maintaining the project, including: + +- providing thought leadership and technical direction +- strategic planning, roadmapping and project management +- managing community infrastructure (e.g., Github repository, etc) +- fostering collaborations with external organisations +- avoiding deadlocks and ensuring a smooth functioning of the project + +SC nominees must be nominated by an existing core developer and receive +affirmative votes from two-thirds of core developers and a simple majority +(50% if there are an even number) of existing SC members. + +Like core developers, SC members who continue to engage with the project +can serve as long as they'd like. However, SC members who do not actively engage +in their SC responsibilities are expected to resign. In the event, a SC member +who no longer engages in their responsibilities does not resign, the remaining +SC members and core developers can vote to remove them (same voting rules +as removal of core developer by steering committee). + +.. _decisions: + +Decision making +=============== + +The ``predictably_core`` community tries to take viewpoints and feedback from all +community members into account when making decisions in order to arrive at +consensus decisions. + +To accomplish this, this section outlines the decision-making process used +by the project. + +Where we make decisions +----------------------- + +Most of the project's decisions and voting takes place on the project’s `issue +tracker `__, +`pull requests `__ or an +:ref:`enhancement proposal `. However, some sensitive discussions and +all appointment votes occur on private chats. + +Core developers are expected to express their consensus (or veto) in the medium +where a given decision takes place. For changes included in the Project's issues +and Pull Requests, this is through comments or Github's built-in review process. + +Types of decisions +------------------ + +The consensus based decision-making process for major types of project +decisions are summarized below. + +.. list-table:: + :header-rows: 1 + + * - Type of change + - Decision making process + * - Code additions or changes + - :ref:`Lazy consensus ` + * - Documentation changes + - :ref:`Lazy consensus ` + * - Changes to the API design, hard dependencies, or supported versions + - :ref:`Lazy consensus ` based on an :ref:`PCEP ` + * - Changes to governance + - :ref:`Lazy consensus ` based on an :ref:`PCEP ` + * - Appointment to core developer or steering committee status + - Anonymous voting on slack + + +How we make decisions +--------------------- + +.. _lazy: + +Lazy consensus +^^^^^^^^^^^^^^ + +Changes are approved "lazily" when after *reasonable* amount of time +the change receives approval from at least one core developer +and no rejections from any core developers. + +This is approach is designed to make it easier to add new features and make changes +to the project as it develops. To make sure things run smoothly, +:ref:`core developers ` should make sure that the *reasonable* time +other community members have to provide feedback on the changes is commensurate +to the scope of the change. For changes to the API or other larger changes, +core developers should actively solicit feedback from their peers. + +.. _gov_pcep: + +``predictably_core`` enhancement proposals +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Project design decisions have a more detailed approval process, +commensurate with their broader impact on the project. Any changes +to the project's core API design, hard dependencies or supported versions +should first be presented in a ``predictably_core`` enhancement proposal (PCEP). + +See the developer guide for more information on creating a :ref:`PCEP `. + +Resolving conflicts +^^^^^^^^^^^^^^^^^^^ + +When consensus can't be found lazily, the project's core developers will vote +to decide how to proceed on an issue. Any core developers can call for a vote +on a topic. A topic must receive two-thirds of core developer votes cast +(abstentions are allowed) via comments on the relevant issue or +Pull Request over a one week voting period. + +In the event a proposed change does not gather the necessary votes, then: + +- The core developer who triggered the vote can choose to drop the issue +- The proposed changes can be escalated to the SC, who will seek to learn more + about the team member viewpoints, before bringing the topic up for a simple + majority vote of SC members. + +.. _acknowledging: + +Acknowledging contributions +=========================== + +The ``predictably_core`` project values all kinds of contributions and the +development team is committed to recognising each of them fairly. + +The project follows the `all-contributors `_ +specification to recognise all contributors, including those that don’t +contribute code. Please see our list of `all contributors `_. + +Please let us know or open a PR with the appropriate changes to +`predictably-core/.all-contributorsrc +`_ +if we have missed anything. + +.. note:: + + ``predictably_core`` is an open-source project. All code is contributed + under `our open-source + license `_. + Contributors acknowledge that they have rights to make their contribution + (code or otherwise) available under this license. + +References +========== + +Our governance model is inspired by various existing governance +structures. In particular, we'd like to acknowledge: + +* `scikit-learn's governance model `_ diff --git a/docs/source/about/overview.rst b/docs/source/about/overview.rst new file mode 100644 index 0000000..eb7bcd4 --- /dev/null +++ b/docs/source/about/overview.rst @@ -0,0 +1,101 @@ +.. _learn_about_us: + +================================ +Learn About ``predictably_core`` +================================ + +.. _mission: + +Mission +======= + +``predictably_core``'s goal is to make it easier for end users from a vareity +of backgrounds to reuse `scikit-learn`_ and `sktime`_ style design patterns in +their own projects. + +Therefore, ``predictably_core`` includes functionality to help make the creation of +packages following these design patterns *predictable*. + +Check out our :ref:`roadmap` for more details on how we plan achieve our mission. + +.. _history: + +History +======= + +``predictably_core`` was started in 2024 by Ryan Kuhns. + +The project builds on and was heavily inspired by Ryan's work on `skbase`_ with +Franz Kiraly. In turn, the `skbase`_ project drew its inspiration from +the Python interfaces used by `scikit-learn`_ (particularly the `BaseEstimator API`_) +and `sktime`_. + +Development is supported by the project's steering committee, core developers +and the broader community (see `contributors `_). + +If you are interested in contributing, check out our +:ref:`Contributing ` guide. + +.. _scikit-learn: https://scikit-learn.org/stable/index.html +.. _BaseEstimator API: https://scikit-learn.org/stable/developers/develop.html +.. _sktime: https://www.sktime.net/en/stable/index.html +.. _skbase: https://skbase.readthedocs.io/en/latest/index.html + +.. _team: + +Development Team +================ + +For more information about each of these roles, see ``predictably_core``'s +:ref:`governance` document. A list of all contributors can be found under +the `contributors `_ section. + +Steering Committee +------------------ + +``predictably_core``'s steering committee is is made up of a subset of +`core developers `_ who help the project manage its goals and make +key decisions. + +.. list-table:: + :header-rows: 1 + + * - Name + - GitHub ID + * - Ryan Kuhns + - :user:`rnkuhns` + +Code of Conduct Committee +------------------------- +Everyone involved in the ``predictably_core`` is expected to treat others with +respect, and promote an inclusive and collaborative environment. The Code +of Conduct Committee is designed to ensure these values are followed. + +.. list-table:: + :header-rows: 1 + + * - Name + - GitHub ID + * - Ryan Kuhns + - :user:`rnkuhns` + +.. note:: + + The intent is to have a code of conduct committee separate from the steering + committee once the project community expands. + +.. _core_devs: + +Core Developers +--------------- +Core developers help manage the project by contributing code, providing feedback, +reviewing code, and answering questions about the project. They also help develop +the project's :ref:`roadmap`. + +.. list-table:: + :header-rows: 1 + + * - Name + - GitHub ID + * - Ryan Kuhns + - :user:`rnkuhns` diff --git a/docs/source/about/roadmap.rst b/docs/source/about/roadmap.rst new file mode 100644 index 0000000..633f6e5 --- /dev/null +++ b/docs/source/about/roadmap.rst @@ -0,0 +1,24 @@ +.. _roadmap: + +======= +Roadmap +======= + +Welcome to ``predictably_core``'s roadmap. + +.. note:: + + The project is under active planning and development. We will continue to update + our roadmap as the project matures and we plan future work. + +Project Goals +============= + +``predictably_core``'s goal is to help users predict *ably*. + +To accomplish this we plan to: + +- Provide an intuitive interface similar to `scikit-learn`_. +- Have best in class documentation. + +.. _scikit-learn: https://scikit-learn.org/stable/index.html diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst new file mode 100644 index 0000000..b78467b --- /dev/null +++ b/docs/source/api_reference.rst @@ -0,0 +1,104 @@ +.. _api_ref: + +=== +API +=== + +This is the API reference for ``predictably_core``. For additional details on using +the functionality provided by the API see the :ref:`user_guide`. See the +:ref:`glossary` for common terms used throughout the package. + +.. automodule:: predictably_core + :no-members: + :no-inherited-members: + +Configure ``predictably_core`` +============================== + +.. automodule:: predictably_core.config + :no-members: + :no-inherited-members: + +.. currentmodule:: predictably_core.config + +.. autosummary:: + :toctree: api_reference/auto_generated/ + :template: function.rst + + get_config + set_config + reset_config + config_context + +.. _obj_core: + +Core +==== + +.. automodule:: predictably_core.core + :no-members: + :no-inherited-members: + +.. currentmodule:: predictably_core.core + +Base Classes +------------ + +.. autosummary:: + :toctree: api_reference/auto_generated/ + :template: class.rst + + BaseObject + BaseEstimator + +Tools for Working with Base Classes +----------------------------------- + +.. autosummary:: + :toctree: api_reference/auto_generated/ + :template: function.rst + + clone + +.. _obj_validation: + +Validation +========== + +.. automodule:: predictably_core.validate + :no-members: + :no-inherited-members: + +.. currentmodule:: predictably_core.validate + +.. autosummary:: + :toctree: api_reference/auto_generated/ + :template: function.rst + + check_mapping + check_path + check_sequence + check_type + is_iterable + is_mapping + is_sequence + +Utilities +========= + +.. automodule:: predictably_core.utils + :no-members: + :no-inherited-members: + +.. currentmodule:: predictably_core.utils + +.. autosummary:: + :toctree: api_reference/auto_generated/ + :template: function.rst + + compare_mappings + format_sequence_to_str + remove_type_text + scalar_to_sequence + single_element_sequence_to_scalar + update_dict_at diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 0000000..f6cf854 --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1,3 @@ +.. _top_level_changelog: + +.. include:: user_documentation/changelog.rst diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..ffba657 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,316 @@ +"""Configure Sphinx documentation builder. + +Provides information needed to build docs. Includes HTML theme and other options. +""" + +import datetime +import inspect +import os +import sys +from pathlib import Path + +import predictably_core + +# -- Project information --------------------------------------------------- +current_year = datetime.datetime.now().year +if current_year > 2024: + current_year = f"2024-{current_year}" + +org = "predict-ably" +project = "predictably-core" +copyright = f"{current_year}, {org} developers (BSD-3 License)" # noqa: A001 +author = "predict-ably developers" + +release = predictably_core.__version__ + +version = predictably_core.__version__ +github_tag = f"v{version}" + +# -- Path setup -------------------------------------------------------------- + +# When we build the docs on readthedocs, we build the package and want to +# use the built files in order for sphinx to be able to properly read the +# Cython files. Hence, we do not add the source code path to the system path. +env_rtd = os.environ.get("READTHEDOCS") +# Check if on Read the docs +if env_rtd != "True": + print("Not on ReadTheDocs") # noqa: T201 + sys.path.insert(0, Path("../..").resolve()) +else: + rtd_version = os.environ.get("READTHEDOCS_VERSION") + if rtd_version == "latest": + github_tag = "main" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autosectionlabel", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.linkcode", # link to GitHub source code via linkcode_resolve() + "myst_parser", + "numpydoc", + "sphinx_copybutton", + "sphinx_design", + "sphinx_issues", +] + +myst_enable_extensions = ["colon_fence"] +myst_heading_anchors = 2 + +# 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", "**.ipynb_checkpoints"] + +# -- Internationalization ------------------------------------------------ +# specifying the natural language populates some key tags +language = "en" + +# Use bootstrap CSS from theme. +panels_add_bootstrap_css = False + +# 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": "restructuredtext", + ".md": "markdown", +} + +# The main toctree document. +master_doc = "index" + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# Members and inherited-members default to showing methods and attributes from +# a class or those inherited. +# Member-order orders the documentation in the order of how the members are +# defined in the source code. +autodoc_default_options = { + "members": True, + "inherited-members": True, + "member-order": "bysource", +} + +# generate autosummary even if no references +autosummary_generate = True + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = False + +# Link to GitHub repo for github_issues extension +issues_github_path = f"{org}/{project}" + + +def linkcode_resolve(domain, info): + """Return URL to source code corresponding. + + Used to link docs to github code. + + Parameters + ---------- + domain : str + Domain for resolving linked code. + info : dict + Info about linked code. + + Returns + ------- + str + The string version URL to linked code. + """ + + def find_source(): # numpydoc ignore=RT01 + """Find the file and line number (if possible). + + Implementation is based on numpy. + """ + # https://github.com/numpy/numpy/blob/main/doc/source/conf.py#L286 + obj = sys.modules[info["module"]] + for part in info["fullname"].split("."): + obj = getattr(obj, part) + + fn = inspect.getsourcefile(obj) + fn = os.path.relpath(fn, start=Path(predictably_core.__file__).parent) + source, lineno = inspect.getsourcelines(obj) + return fn, lineno, lineno + len(source) - 1 + + if domain != "py" or not info["module"]: + return None + try: + filename = f"{project}/%s#L%d-L%d" % find_source() + except Exception: + filename = info["module"].replace(".", "/") + ".py" + return f"https://github.com/{org}/{project}/blob/{version_match}/{filename}" + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" + +# Define the json_url for our version switcher. +json_url = "https://predictably-core.readthedocs.io/en/latest/_static/switcher.json" + +# This uses code from the py-data-sphinx theme's own conf.py +# Define the version we use for matching in the version switcher. +version_match = os.environ.get("READTHEDOCS_VERSION") + +# If READTHEDOCS_VERSION doesn't exist, we're not on RTD +# If it is an integer, we're in a PR build and the version isn't correct. +if not version_match or version_match.isdigit(): + # For local development, infer the version to match from the package. + if "dev" in release or "rc" in release: + version_match = "latest" + # We want to keep the relative reference if we are in dev mode + # but we want the whole url if we are effectively in a released version + json_url = "_static/switcher.json" + else: + version_match = "v" + release + +html_show_sourcelink = False +html_theme_options = { + "logo": { + "text": "predictably-core", + "alt_text": f"{project}", + }, + "icon_links": [ + { + "name": "GitHub", + "url": f"https://github.com/{org}/{project}", + "icon": "fab fa-github", + }, + { + "name": "Slack", + "url": f"https://join.slack.com/t/{org}/shared_invite/zt-21ezi33ip-WGJCUBCWc5yVrr6FOsARaw", + "icon": "fab fa-slack", + }, + { + "name": "PyPI", + "url": f"https://pypi.org/project/{project}", + "icon": "fa-solid fa-box", + }, + ], + "icon_links_label": "Quick Links", + "show_nav_level": 1, + "show_prev_next": False, + "use_edit_page_button": False, + "navbar_start": ["navbar-logo", "version-switcher"], + "navbar_center": ["navbar-nav"], + "switcher": { + "json_url": json_url, + "version_match": version_match, + }, + "header_links_before_dropdown": 6, + "secondary_sidebar_items": { + "**": ["page-toc", "edit-this-page"], + "about": [], + "contribute": [], + "users": [], + }, +} + +html_context = { + "github_user": f"{org}", + "github_repo": f"{project}", + "github_version": "main", + "doc_path": "docs/source/", + "default_mode": "light", +} +html_sidebars = { + "**": ["sidebar-nav-bs.html", "sidebar-ethical-ads.html"], + "get_started": [], + "get_involved": [], + "changelog": [], +} + +# 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"] + +# -- Options for HTMLHelp output --------------------------------------------- +# Output file base name for HTML help builder. +htmlhelp_basename = "predictably-coredoc" + + +# -- 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, + "predictably-core.tex", + "predictably-core Documentation", + "predict-ably developers", + "manual", + ), +] + +# 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, + "predictably-core", + "predictably-core Documentation", + author, + "predictably-core", + "Build predictable Python packages.", + "Miscellaneous", + ), +] + +# -- 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, "predictably-core", "predictably-core Documentation", [author], 1) +] + +# -- Extension configuration ------------------------------------------------- +# -- Options for numpydoc extension ------------------------------------------ +# see http://stackoverflow.com/q/12206334/562769 +numpydoc_show_class_members = True +# this is needed for some reason... +# see https://github.com/numpy/numpydoc/issues/69 +numpydoc_class_members_toctree = False + +numpydoc_validation_checks = {"all", "GL01", "SA01"} +numpydoc_validation_exclude = [r".\\tests\\.*", r"\.__init__$"] + +# -- Options for sphinx-copybutton extension---------------------------------- +copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " +copybutton_prompt_is_regexp = True +copybutton_selector = ":not(.prompt) > div.highlight pre" + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + "python": (f"https://docs.python.org/{sys.version_info.major}", None), + "numpy": ("https://docs.scipy.org/doc/numpy/", None), + "scipy": ("https://docs.scipy.org/doc/scipy/reference", None), + "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), + "scikit-learn": ("https://scikit-learn.org/stable/", None), +} diff --git a/docs/source/get_involved.rst b/docs/source/get_involved.rst new file mode 100644 index 0000000..0d1bde0 --- /dev/null +++ b/docs/source/get_involved.rst @@ -0,0 +1,136 @@ +.. _contrib_guide: + +============ +Get Involved +============ + +``predictably_core`` is a community-driven project, built by volunteers. Your help +improving the package is extremely welcome. Our goal is to make it easy to +contribute. If you'd like to contribute, but run into any issues, please reach +out on `Github`_. + +.. _how_to_contrib: + +How You Can Contribute +====================== + +You can contribute to ``predictably_core`` in a variety of ways. This includes: + +- Contributing code (see our :ref:`roadmap ` for information our planned + development), +- helping improve the package's documentation, +- helping improve our package maintenance practices and Github workflows, +- providing feedback and weighing in on existing issues on `Github issues`_, our +- suggesting new features by opening `Github issues`_ that explain the new features + you'd like to see. + +The ``predictably_core`` team is also happy to support new contributors and +individuals looking to develop their skills. + +If you want to get started contributing, we recommend: + +- Saying hello on `Slack`_ +- Using our :ref:`developer guide ` to setup a contributing environment +- Picking a good first `issue `_ to work on that will let you get + familiar with our contributing process + +Once your first Pull Request is merged you may decide to continue contributing +regularly. Talk with the development team on `Slack`_ about your interests and +how you can best contribute to the project. + +.. warning:: + + Everyone is welcome to participating in the ``predictably_core`` project. To + ensure that everyone feels welcome, all contributors are expected to follow + the ``predictably_core`` :ref:`code of conduct `. + +.. _dev_guide: + +Development Guide +================= + +If you are ready to start contributing to ``predictably_core`` it is important to +understand our development practices. + +.. toctree:: + :maxdepth: 1 + :hidden: + + get_involved/dev_installation + get_involved/git_workflow + get_involved/ci + get_involved/coding_standards + get_involved/creating_docs + get_involved/testing_framework + get_involved/dependencies + get_involved/reviewer_guide + get_involved/enhancement_proposal + get_involved/release_instructions + +.. grid:: 1 2 2 2 + :gutter: 3 + + .. grid-item-card:: Installation + :text-align: left + :link: get_involved/dev_installation + :link-type: doc + + Complete a developer installation. + + .. grid-item-card:: Git Workflow + :text-align: left + :link: get_involved/git_workflow + :link-type: doc + + Our Git and Github workflow. + + .. grid-item-card:: Continuous Integration + :text-align: left + :link: get_involved/ci + :link-type: doc + + Continuous Integration. + + .. grid-item-card:: Coding Standards + :text-align: left + :link: get_involved/coding_standards + :link-type: doc + + Our code requirements. + + .. grid-item-card:: Documentation Standards + :text-align: left + :link: get_involved/creating_docs + :link-type: doc + + Our documentation requirements + + .. grid-item-card:: Testing Framework + :text-align: left + :link: get_involved/testing_framework + :link-type: doc + + .. grid-item-card:: Dependency Management + :text-align: left + :link: get_involved/dependencies + :link-type: doc + + How we manage dependencies + + .. grid-item-card:: Proposing Enhancements + :text-align: left + :link: get_involved/enhancement_proposal + :link-type: doc + + How to propose major changes + + .. grid-item-card:: Release Instructions + :text-align: left + :link: get_involved/release_instructions + :link-type: doc + + How to prepare a new release + +.. _Github: https://github.com/predict-ably/predictably-core/ +.. _Github issues: https://github.com/predict-ably/predictably-core/issues +.. _Slack: https://join.slack.com/t/predict-ably/shared_invite/zt-21ezi33ip-WGJCUBCWc5yVrr6FOsARaw # noqa diff --git a/docs/source/get_involved/ci.rst b/docs/source/get_involved/ci.rst new file mode 100644 index 0000000..e01e089 --- /dev/null +++ b/docs/source/get_involved/ci.rst @@ -0,0 +1,93 @@ +.. _ci: + +====================== +Continuous integration +====================== + +.. _Github Actions: https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions +.. _precommit.ci: https://pre-commit.ci/ + +``predictably_core`` uses `Github Actions`_ continuous integration (CI) services +to ensure contributions meet the project's standards. See the sections below to +see how the project automatically validates code quality, and builds and tests +your changes. + +Code quality checks +=================== + +``predictably_core`` uses `pre-commit.ci `_ to help maintain +the project's :ref:`coding style `, by automating the code quality +checks spelled out in the .pre-commit-config.yaml in the project's root directory. +These checks run automatically when you open a Pull Request or push a new commit +to an existing Pull Request. + +When starting your development in your own local clone of the repository, +you should use your command line tool to run :code:`pre-commit install` (the +:ref:`developer installation instructions ` include this step). This +will setup pre-commit locally, and trigger the repositories pre-commit hooks +to run prior committing your code locally. + +.. note:: + + The project also continues to make use of the deprecated + `pre-commit github action `_, because + it makes it easy cancel other continuous integration steps + (including unit testing). This duplicates the code quality portion of the + CI routine, but enables the longer unit testing portion of the CI routine + to be cancelled whenever the code quality portion fails. A contribution + that enables Github Action workflows to be cancelled when + `pre-commit.ci `_ fails, would be greatly appreciated. + +Testing +======= + +``predictably_core`` uses `pytest `_ for testing. +To check if your code passes all tests locally, follow ``predictably_core``'s +:ref:`development installation ` instructions, which will install +``pytest`` along with other development tools. + +With ``pytest`` installed, you can navigate to your local project's root directory +and run: + +.. code:: bash + + pytest ./predictably_core + +Infrastructure +============== + +This section gives an overview of the infrastructure and continuous +integration services ``predictably_core`` uses. + ++---------------+-----------------------+-------------------------------------+ +| Platform | Operation | Project Configuration | ++===============+=======================+=====================================+ +| `GitHub | Build/test/ | `.github/workflows/ `_ | ++---------------+-----------------------+-------------------------------------+ +| `pre-commit.ci| Automate code quality | `.pre-commit-config.yml | +| `_ | | .pre-commit-config.yaml>`_ | ++---------------+-----------------------+-------------------------------------+ +| `Read the | Build/deploy | `.readthedocs.yaml | +| Docs `__ | | .readthedocs.yaml>`_ | ++---------------+-----------------------+-------------------------------------+ +| `Codecov | Test coverage | `.codecov.yml `__ | | predictably-core/blob/main/ | +| | | .codecov.yml>`_, | +| | | `.coveragerc `_ | ++---------------+-----------------------+-------------------------------------+ + +Additional scripts used for code quality, building, unit testing and +distribution can be found in `build_tools/`_. + +.. _build_tools/: https://github.com/predict-ably/predictably-core/tree/main/build_tools diff --git a/docs/source/get_involved/coding_standards.rst b/docs/source/get_involved/coding_standards.rst new file mode 100644 index 0000000..060f72f --- /dev/null +++ b/docs/source/get_involved/coding_standards.rst @@ -0,0 +1,100 @@ +.. _code_standards: + +================ +Coding standards +================ + +.. _code_style: + +Coding style +============ + +``predictably`` follows standard Python code style conventions, including the +`PEP8 `_ coding guidelines. + +Code formatting and linting +--------------------------- + +``predictably`` uses a variety of tools to enforce code formatting conventions, +including: + +* `black `_ with configuration in + ``pyproject.toml`` +* `flake8 `__ with configurations in ``setup.cfg`` +* `isort `_ with configuration in ``pyproject.toml`` +* `pydocstyle `_ with configuration in + ``pyproject.toml`` +* `doc8 `_ with configuration in ``pyproject.toml`` +* `bandit `_ with configuration in + ``pyproject.toml`` +* ``numpydoc`` to enforce numpy `docstring standard + `_ , +* ``predictably`` specific conventions described in our + :ref:`documentation conventions `. + +All of these conventions (except for predictably's specific documentation conventions +are automatically run on Pull Requests using ``predictably``'s :ref:`ci` workflows. + +Setting up local code quality checks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When starting your development in your own local clone of +the repository, you should enable ``pre-commit`` locally so the code formatting +and linting tools are run prior to committing your code locally. + +Using pre-commit locally +^^^^^^^^^^^^^^^^^^^^^^^^ + +To set up pre-commit, follow ``predictably``'s +:ref:`development installation ` instructions. Then navigate to +the directory of your local clone of your forked repository and run +:code:`pre-commit install`. + +Once installed, pre-commit will automatically run all ``predictably`` code +quality checks on the files you changed whenever you make a new commit. + +You can find all of ``predictably``'s pre-commit configurations in +`.pre-commit-config.yaml +`_. + +.. note:: + + To exclude a line of code from being checked by flake8, you can add a ``# noqa`` + (no quality assurance) comment at the end of that line. However, this is + generally discouraged unless no other options for passing the code quality + checking are possible. In this case, provide a comment indicating the + reasoning above the line. + + There are similar ways to exclude lines from the other code quality tools. But, + the same logic of discouraging this approach unless no other solution for + passing the code quality check exists. + +Integrating with your local developer IDE +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Local developer IDEs often provide integration with with common code quality +checks, but require you to set them up in the IDE specific ways. + +Visual Studio Code allows you to run code quality checks including +``black``, ``flake8``, ``isort``, ``pydocstyle`` and/or ``numpydoc`` on save. +However, they need to be activated individually in the VS Code preferences ( +or set in your local ``settings.json`` file). If you want to easily Install all +the linters in your environment use the hint in the +:ref:`development installation ` instructions and run +:code:`pip install --editable .[dev,test,linters]`. + +In Visual Studio Code, we also recommend to add ``"editor.ruler": [79, 88]`` +to your local ``settings.json`` to display the max line length. + +``predictably`` specific code formatting conventions +---------------------------------------------------- + +- Check out our :ref:`glossary`. +- Avoid multiple statements on one line. Prefer a line return after a + control flow statement (``if``/``for``). +- Use absolute imports for references inside ``predictably``. +- Don’t use ``import *`` in the source code. It is considered + harmful by the official Python recommendations. It makes the code + harder to read as the origin of symbols is no longer explicitly + referenced, but most important, it prevents using a static analysis + tool like pyflakes to automatically find bugs. diff --git a/docs/source/get_involved/creating_docs.rst b/docs/source/get_involved/creating_docs.rst new file mode 100644 index 0000000..5c878b7 --- /dev/null +++ b/docs/source/get_involved/creating_docs.rst @@ -0,0 +1,218 @@ +.. _developer_guide_documentation: + +======================= +Documentation standards +======================= + +Providing instructive documentation is a key part of ``predictably``'s mission. +To meet this, developers are expected to follow the project's documentation standards. + +These include: + +* Documenting code using NumPy-style docstrings +* Following ``predictably``'s docstring convention for public code artifacts and modules +* Adding new public functionality to the :ref:`api_ref` + and :ref:`user guide ` +* Including a description of the algorithm in the applicable portion of the + online text accompanying the package. + +More detailed information on ``predictably``'s documentation format is provided below. + +Docstring conventions +===================== + +``predictably`` uses the numpydoc_ Sphinx extension and follows the +`NumPy docstring format `_. + +To ensure docstrings meet expectations, ``predictably`` uses a combination of +validations built into numpydoc_, pydocstyle_ pre-commit checks +(set to the NumPy convention) and automated testing of docstring examples to +ensure the code runs without error. + +However, the automated docstring validation in pydocstyle_ only covers basic +formatting. Passing these tests is necessary to meet the ``predictably`` +docstring conventions, but is not sufficient for doing so. + +To ensure docstrings meet ``predictably``'s conventions, developers are expected +to check their docstrings against numpydoc_ and ``predictably`` conventions and +:ref:`reviewer's ` are expected to also focus feedback on +docstring quality. + +``predictably`` specific conventions +------------------------------------ + +Beyond basic NumPy docstring formatting conventions, developers should focus on: + +- Ensuring all parameters (classes, functions, methods) and attributes (classes) + are documented completely and consistently +- Including links to the relevant topics in the :ref:`glossary` or + :ref:`user_guide` in the extended summary +- Including an `Examples` section that demonstrates at least basic functionality + in all public code artifacts +- Adding a `See Also` section that references related ``predictably`` code + artifacts as applicable +- Including citations to relevant sources in a `References` section + +Accordingly, most public code artifacts in ``predictably`` +should generally include the following NumPy docstring convention sections: + +1. Summary +2. Extended Summary +3. Parameters +4. Attributes (classes only) +5. Returns or Yields (as applicable) +6. Raises (as applicable) +7. See Also (as applicable) +8. Notes (as applicable) +9. References (as applicable) +10. Examples + +.. note:: + + In many cases a parameter, attribute, return, or error may be described + in the docstring of more than one class. To avoid confusion, developers + should make sure their docstrings are as similar as possible to existing + docstring descriptions of the the same parameter, attribute, return + or error. As applicable, this may mean copying the same docstring + section for the parameter, attribute, return or error. + +Summary and extended summary +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The summary should be a single line, followed by a (properly formatted) +extended summary. + +The extended summary should include a user friendly explanation +of the code artifacts functionality. The extended summary should also include +links to relevant content in the :ref:`glossary` and :ref:`user guide `. + +If a "term" already exists in the glossary and the developer wants to link it +directly they can use: + +.. code-block:: + + :term:`the glossary term` + +In other cases you'll want to use different phrasing but link to an existing +glossary term, and the developer can use: + +.. code-block:: + + :term:`the link text ` + +In the event a term is not already in the glossary, developers should add the term +to the :ref:`glossary` and include a reference (as shown above) to the added term. + +Likewise, a developer can link to a particular area of the user guide by including +an explicit cross-reference and following the steps for referencing in Sphinx +(see the helpful description on +`Sphinx cross-references +`_ +posted by Read the Docs). Again developers are encouraged to add important content +to the user guide and link to it if it does not already exist. + +See Also +~~~~~~~~ + +This section should reference other ``predictably`` code artifacts related to the code +artifact being documented by the docstring. Developers should use judgement in +determining related code artifacts. + +Notes +~~~~~ + +The notes section can include several types of information, including: + +- Mathematical details of a code object or other important implementation details + (using ..math or :math:`7+3` functionality) +- Links to alternative implementations of the code artifact that are external to + ``predictably`` +- A summary of the aspects of an object's state that are updated by state + changing methods + +References +~~~~~~~~~~ + +Objects that implement functionality covered in a research article, book or +other package, should include an applicable citation. + +This should be done by adding references into the references section of the docstring, +and then typically linking to these in other parts of the docstring. + +The references you intend to link to within the docstring should follow a very specific +format to ensure they render correctly. See the example below. Note the space between +the ".." and opening bracket, the space after the closing bracket, and how all the +lines after the first line are aligned immediately with the opening bracket. +Additional references should be added in exactly the same way, but the number +enclosed in the bracket should be incremented. + +.. code-block:: rst + + .. [1] Some research article, link or other type of citation. + Long references wrap onto multiple lines, but you need to + indent them so they start aligned with opening bracket on first line. + +To link to the reference labeled as "[1]", you use "[1]\_". This only works within +the same docstring. Sometimes this is not rendered correctly if the "[1]\_" link is +preceded or followed by certain characters. If you run into this issue, try +putting a space before and following the "[1]\_" link. + +To list a reference but not link it elsewhere in the docstring, you can leave +out the ".. [1]" directive as shown below. + +.. code-block:: rst + + Some research article, link or other type of citation. + Long references wrap onto multiple lines. If you are + not linking the reference you can leave off the ".. [1]". + +Examples +~~~~~~~~ + +Most code artifacts in ``predictably`` should include an examples section. At +a minimum this should include a single example that illustrates basic functionality. + + +The examples should use simple data (e.g. randomly generated data, etc) +generated using a ``predictably`` dependency and wherever possible only depend +on ``predictably`` or its core dependencies. Examples should also be designed to +run quickly where possible. For quick running code artifacts, additional examples +can be included to illustrate the affect of different parameter settings. + +.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/index.html +.. _pydocstyle: http://www.pydocstyle.org/en/stable/ +.. _sphinx: https://www.sphinx-doc.org/ +.. _readthedocs: https://readthedocs.org/projects/predictably/ + +Documentation Build +------------------- + +We use `sphinx`_ to build our documentation and `readthedocs`_ to host it. +You can find our latest documentation `here `_. + +The source files can be found +in `docs/source/ `_. +The main configuration file for sphinx is +`conf.py `_ +and the main page is +`index.rst `_. +To add new pages, you need to add a new ``.rst`` file and link to it from the +applicable file in the existing documentation. + +To build the documentation locally, you need to install a few extra +dependencies listed in +`pyproject.toml `_. + +1. To install extra dependencies from the root directory of your local copy + of the forked repository, run: + + .. code:: bash + + pip install --editable .[docs] + +2. To build the website locally, from the root directory of your local copy, run: + + .. code:: bash + + cd docs + make html diff --git a/docs/source/get_involved/dependencies.rst b/docs/source/get_involved/dependencies.rst new file mode 100644 index 0000000..bb93873 --- /dev/null +++ b/docs/source/get_involved/dependencies.rst @@ -0,0 +1,92 @@ +.. _deps: + +============ +Dependencies +============ + +Types of dependencies +===================== + +``predictably`` has three types of dependencies: + +* "core" dependencies that are required for ``predictably`` to install and run +* "soft" dependencies that are required to import or use specific, + non-core functionality +* "developer" dependencies are required for developing ``predictably`` but not + required of end-users (e.g., ``pre-commit``) +* "test" dependencies are required for running ``predictably``'s unit tests + +Making it easy to install and use ``predictably`` in a variety of projects is +on of ``predictably``'s goals. Therefore, we seeks to minimizing the number of +dependencies needed to provide the proejct's functionality. + +Soft Dependencies +================= + +A soft dependency is a dependency that is only required to import +certain modules, but not necessary to use most of the package's functionality. +Accordingly, soft dependencies are not automatically installed alongside +``predictably``. If you want to install soft dependencies, you'll either need +to do so manually or use follow the installation instructions and install +the optional "[all_extras]" version of the package. + +Adding a soft dependency +------------------------ + +The project tries to keep its dependencies, including soft dependencies, +minimized. Core developers will consider the pros and cons of any additional +soft dependency when reviewing Pull Requests. In the event you need to add a new +soft dependency or changing the version of an existing one, +the following files need to be updated: + +* `pyproject.toml `_, + adding the dependency or version bounds in the ``all_extras`` dependency set. + Following the `PEP 621 `_ convention, + all dependencies including build time dependencies and optional dependencies + are specified in this file. + +Informative warnings or error messages for missing soft dependencies should be raised, +in a situation where a user would need them. This is handled through our +``check_soft_dependencies`` `utility +`_. + +There are specific conventions to add such warnings in ``BaseObject``-s. +To add ``BaseObject`` with a soft dependency, ensure the following: + +* imports of the soft dependency only happen inside the object + (e.g., a particular methods or in ``__init__`` after calls to + ``super(cls).__init__``). +* the ``python_dependencies`` tag of the ``BaseObject`` is populated with a ``str``, + or a ``list`` of ``str``, of import dependencies. Exceptions will automatically + raised when constructing the ``BaseObject`` in an environment without the + required packages. +* in the python module containing the ``BaseObject``, the + ``check_soft_dependencies`` utility is called at the top of the module, + with ``severity="warning"``. This will raise an informative warning message + at module import. +* In a case where the package import differs from the package name (i.e., + ``import package_string`` is different from + ``pip install different-package-string``), the ``check_soft_dependencies`` + utility should be used in ``__init__``. Both the warning and constructor call + should use the ``package_import_alias`` argument for this. +* If the soft dependencies require specific python versions, the ``python_version`` + tag should also be populated, with a PEP 440 compliant version specification + ``str`` such as ``"<3.10"`` or ``">3.6,~=3.8"``. + +Core or developer dependencies +============================== + +Core and developer dependencies can only be added by core developers after +discussion in a core developer meeting or in the project's communication channels. + +When adding a new core dependency or changing the version of an existing one, +the following files need to be updated: + +* `pyproject.toml `_, + adding the dependency or version bounds in the ``dependencies`` dependency set. + +When adding a new developer dependency or changing the version of an existing one, +the following files need to be updated: + +* `pyproject.toml `_, + adding the dependency or version bounds in the ``dev`` dependency set. diff --git a/docs/source/get_involved/dev_installation.rst b/docs/source/get_involved/dev_installation.rst new file mode 100644 index 0000000..204688c --- /dev/null +++ b/docs/source/get_involved/dev_installation.rst @@ -0,0 +1,227 @@ +.. _dev_install: + +============================== +Development Installation Guide +============================== + +If you plan on contributing to ``predictably_core`` you'll want a development +installation. Follow the instructions below to install the latest development +version of ``predictably_core``. + +1. Fork the ``predictably_core`` `Github repository`_ +2. Create a local clone of your fork +3. Link your local clone to the original ``predictably_core`` `Github repository`_ +4. Sync the main branch of your local clone +5. Create a new virtual environment via ``conda`` and activate it. +6. Complete an "editable" installation of ``predictably_core`` +7. Initialize ``pre-commit`` so that ``predictably_core``'s static code quality + analysis runs before any contributions you make can be committed to your + local clone. + +Detailed instructions for each step are provided below. + + +Step 1: Fork the Github repository +================================== + +Fork the ``predictably-core`` `Github repository`_ by clicking on the 'Fork' button +near the top right of the page. This creates a copy of the code under your +GitHub user account. For more details on how to fork a repository see this Github +`help article `_. + +Step 2: Clone Your Fork of the Github repository +================================================ + +The ``predictably_core`` `Github repository`_ should be cloned to a local directory. + +To install the latest version using the ``git`` command line, use the following steps: + +1. Use your command line tool to navigate to the directory where you want to clone + ``predictably_core`` +2. Clone the repository: + :code:`git clone https://github.com/predict-ably/predictably-core.git` +3. Move into the root directory of the package's local clone: + :code:`cd predictably-core` +4. Make sure you are on the main branch: :code:`git checkout main` +5. Make sure your local version is up-to-date: :code:`git pull` + +See Github's `repository clone documentation`_ for additional details. + +.. hint:: + + If you want to checkout an earlier version of ``predictably_core`` you can use the + following git command line after cloning to run: :code:`git checkout ` + + Where ```` is a valid version string that can be found by inspecting the + repository's ``git`` tags, by running ``git tag``. + + You can also download a specific release version from the Github repository's + zip archive of + `releases `_. + +Step 3: Link Your Local Clone to the Original Github repository +=============================================================== + +Your fork will be automatically set as the "origin" for your local clone. But you +will need to configure your local clone so that the original ``predictably_core`` +`Github repository`_ is set as the "upstream" remote. + +To do this, first check that your fork is listed as the "origin" for you local clone: + +.. code:: bash + + git remote -v + > origin https://github.com//predictably-core.git (fetch) + > origin https://github.com//predictably-core.git (push) + +Then configure your local clone to add the original repository as its upstream remote: + +.. code:: bash + + git remote add upstream https://github.com/predict-ably/predictably-core.git + +Finally, you'll want to verify that the original repository has been successfully +set as the "upstream" remote and your fork remains the "origin" remote: + +.. code:: bash + + git remote -v + > origin https://github.com//predictably-core.git (fetch) + > origin https://github.com//predictably-core.git (push) + > upstream https://github.com/predict-ably/predictably-core.git (fetch) + > upstream https://github.com/predict-ably/predictably-core.git (push) + + +Step 4: Sync the Main Branch of Your Local Clone +================================================ +In the previous step you set the original repository as your "upstream" remote. +You'll want to make sure the main branch of your local clone is synced with +the original repository (upstream remote). + +`Sync`_ the ``main`` branch of your fork with the upstream repository by running: + +.. code:: bash + + git fetch upstream + git checkout main + git merge upstream/main + + +.. hint:: + + You can use these same instructions to sync another branch by replacing + the "main" branch with the name of the other branch you want to sync. + +Step 5: Create a new virtual environment +========================================= + +Setting up a new virtual environment before building ``predictably_core`` ensures that +conflicting package versions are not installed in the same environment. +You can choose your favorite env manager for this but the example below shows the +steps to create an environment using ``conda``: + +1. Use your command line tool to first confirm ``conda`` is present on your + system: :code:`conda --version` +2. Create a new virtual environment named ``predictably-core-dev`` with python version + ``3.8`` or greater: :code:`conda create -n predictably-core-dev python=3.12` +3. Activate this newly created environment: :code:`conda activate predictably-core-dev` + +Step 6: Complete an Editable Install +==================================== + +When contributing to the project, you will want to install ``predictably_core`` locally, +along with additional development dependencies. You'll be best served by installing +``predictably_core`` in an "editable" mode so that the the package updates each +time the local source code is changed. + +However, ``conda develop`` is not really maintained (see `conda develop Github issue`_). +The workaround is to use ``pip``'s ability to install a package in `editable mode`_ +within your ``conda`` environment. But there can be some issues with ``pip`` installed +dependencies in your ``conda`` environment in some cases. With this in mind, you have +two options: + +1. Pre-install the ``predictably_core`` dependencies, as well as the + packages used to develop ``predictably_core`` in your environment using ``conda``. +2. Allow ``pip`` to install the dependencies in your ``conda`` environment while + it installs ``predictably_core`` in `editable mode`_. + +Follow the instructions for your chosen approach to complete the editable installation. + +.. tab-set:: + + .. tab-item:: Pre-Installing Dependencies Using conda + + Assuming you've already navigated to the root directory of your local copy of + the ``predictably_core`` project, you can use ``conda`` to pre-install + dependencies, then have ``pip`` complete the editable install as follows: + + 1. Navigate into the "build_tools" directory: :code:`cd ./build_tools` + 2. Install the dependencies in your ``conda`` environment:\n + :code:`conda env update -n predictably-core-dev --file predictably-core-dev.yaml` + 3. Navigate back your local ``precitably_core`` project root: :code:`cd ..` + 4. Install ``predictably_core`` using ``pip`` without installing + dependencies:\n :code:`pip install --no-build-isolation --no-deps -e .` + + .. tab-item:: Allow pip to Install Dependencies + + If you are okay with ``pip`` installing the package's dependencies and + the developer dependencies, then you can complete the installation in + fewer steps. Assuming you have already navigated to the root of your local + copy of the ``predictably_core`` project directory this can be done by running: + + .. code-block:: bash + + pip install --editable .[dev,test,docs] + + Including the "[dev,test,docs]" modifier makes sure that the additional + developer, test, and documentation dependencies specified in the + ``predictably_core`` pyproject.toml file are also installed. + +.. hint:: + + In either installation approach, the ``.`` may be replaced + with a full or relative path to your local clone's root directory. + +.. hint:: + + Some integrated development environments (IDEs) have built-in extensions + that run many of the static code quality tools that the development + dependency ``pre-commit`` manages to ensure the quality of the code + you contribute to your project. This is helpful because it allows + some of the code quality tools to automatically apply their formatting + or linting as you develop. But in some cases (like older versions + of VS Code) you have to have the static code quality tools installed + in your development environment. If you want to easily install all the + linters used by ``predictably_core`` in your development environment use: + + - :code:`pip install --editable .[dev,test,docs,linters]` when allowing ``pip`` + to install your dependencies. + - Adding a step between steps 3 and 4 in the Pre-Installing Dependencies Using + Conda workflow to install the linter dependencies: + :code:`conda env update -n predictably-core-dev --file predictably-core-lint.yaml` + +Step 7: Initialize ``pre-commit`` Routine +========================================= + +``predictably_core``'s development workflow uses `pre-commit`_ to automatically run +static code quality routines before each commit to your local repository. This +ensures that everyone's contributions meet the expected formatting and code quality +standards. + +These validations are also run in ``predictably_core`` Github repository, but by +enabling them in your local copy of the package, it ensures you can push code +that meets the packages coding norms, speeding up the code review process. + +``pre-commit`` is installed as one of the developer dependencies. Since ``pre-commit`` +is already in your environment, to initialize it you can run: + +.. code-block:: bash + + pre-commit install + +.. _Github repository: https://github.com/predict-ably/predictably-core +.. _repository clone documentation: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository +.. _editable mode: https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs # noqa +.. _conda develop Github issue: https://github.com/conda/conda-build/issues/4251 +.. _pre-commit: https://pre-commit.com/ +.. _sync: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork # noqa diff --git a/docs/source/get_involved/enhancement_proposal.rst b/docs/source/get_involved/enhancement_proposal.rst new file mode 100644 index 0000000..92ffe65 --- /dev/null +++ b/docs/source/get_involved/enhancement_proposal.rst @@ -0,0 +1,46 @@ +.. _bep: + +===================== +Enhancement Proposals +===================== + +Description +=========== + +A ``predictably`` enhancement proposal (PREP) is a software design document +providing information to the ``predictably`` community. +The proposal should provide a rationale and concise technical specification of +the proposed design. + +We intend PREPs to be the primary mechanisms for proposing major changes, +for collecting community input on an issue, and for documenting the design +decisions that have gone into ``predictably``. + +Smaller changes will be discussed and implemented directly on issues and pull requests. + +Existing PREPs +============== + +You can find existing PREPs in the `enhancement_proposals folder`_ in the +package's root directory. + +.. _enhancement_proposals folder: https://github.com/predict-ably/predictably/tree/main/enhancement_proposals + +Submitting a PREP +================= + +To create a new PREP, please copy and use sktime's `template`_ (update any +references to sktime when drafting your PREP) and open a pull request on +the ``predctably`` repository. + +.. _template: https://github.com/sktime/enhancement-proposals/blob/main/TEMPLATE.md + +It is highly recommended that a single PREP contains a single key proposal or new idea. +The more focused the proposal, the more successful it tends to be. +If in doubt, split your PREP into several well-focused ones. + +A PREP should be a consolidated document, including: + +* a concise problem statement, +* a clear description of the proposed solution, +* a comparison with alternative solutions. diff --git a/docs/source/get_involved/git_workflow.rst b/docs/source/get_involved/git_workflow.rst new file mode 100644 index 0000000..10300b2 --- /dev/null +++ b/docs/source/get_involved/git_workflow.rst @@ -0,0 +1,101 @@ +.. _git_workflow: + +Git and GitHub workflow +======================= + +.. note:: + + If your not familiar with ``git`` you may want to start by reviewing + `Git's documentation `_ and then trying + out the workflow. If you get stuck, chat with us on `Slack`_. + +The preferred workflow for contributing to ``predictably_core``'s repository is +to complete a developer installation, then create a new feature branch and +follow a standard git workflow. + +You can complete the workflow by following the steps below: + +1. Follow ``predictably_core``'s :ref:`development installation ` + instructions. + +2. Make sure the ``main`` branch of your fork is `Synced `_ with the + upstream repository you set in your development installation. + + You completed this step as part of the :ref:`development installation ` + instructions, but in case you completed those at a different time, it is a + good practice to make sure your ``main`` branch is still synced with the + original ``predictably_core`` `Github repository`_ + + .. code:: bash + + git fetch upstream + git checkout main + git merge upstream/main + + .. hint:: + + You can use these same instructions to sync another branch by replacing + the "main" branch with the name of the other branch you want to sync. + +3. Create a new ``feature`` branch from the ``main`` branch to hold + your changes: + + .. code:: bash + + git checkout main + git checkout -b + + .. note:: + + Contributions that don't isolate their changes to a ``feature`` branch + will not be accepted. It's good practice to never work on the ``main`` branch. + Always use a ``feature`` branch and name the ``feature`` branch after + your contribution. + +4. Develop your contribution on your feature branch. Add changed files + using ``git add`` and then ``git commit`` files to record your + changes in Git: + + .. code:: bash + + git add + git commit -m "Your short commit message" + +5. When finished, push the changes to your fork with: + + .. code:: bash + + git push --set-upstream origin my-feature-branch + +6. Follow + `these instructions + `_ + to create a pull request from your fork. If your work is still work in progress, + make sure to open a draft pull request. + + .. note:: + + We recommend opening a pull request early, so that other contributors + become aware of your work and can give you feedback early on. + +7. To add more changes related to this feature, simply repeat steps 4 and 5. + + When iterating step 5, you can leave off the command to set the upstream for + your branch, since you already completed that. This means you'll iterate those + steps by running: + + .. code:: bash + + git add + git commit -m "Your short commit message" + git push my-feature-branch + + .. note:: + + Pull requests are updated automatically if you push new changes to the + same branch. This will trigger ``predictably_core``'s + :ref:`continuous integration ` routine to re-run automatically. + +.. _Github repository: https://github.com/predict-ably/predictably-core +.. _Slack: https://join.slack.com/t/predict-ably/shared_invite/zt-21ezi33ip-WGJCUBCWc5yVrr6FOsARaw # noqa +.. _sync: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork # noqa diff --git a/docs/source/get_involved/release_instructions.rst b/docs/source/get_involved/release_instructions.rst new file mode 100644 index 0000000..fbbbf4d --- /dev/null +++ b/docs/source/get_involved/release_instructions.rst @@ -0,0 +1,210 @@ +.. _release: + +================== +Release Management +================== + +This section provides detailed instructions used to release a new version +of ``predictably``. + +This task is carried out by core developers with write access to the ``predictably`` +repository and designated as release managers by the +:ref:`Steering Committee `. + +Summary of release process +========================== + +The release process includes, in sequence: + +* :ref:`prepare for an upcoming release ` +* :ref:`get the release ready ` +* :ref:`release on PyPi ` +* :ref:`release on conda ` +* troubeleshooting and accident remediation, if applicable (see troubeleshooting + tips in each of the prior sections) + +Details follow below. + +.. _cycle_process: + +Release preparation cycle +------------------------- + +``predictably`` aims for a release every month, typically coinciding with the start of +the month. To ensure releases go smoothly, the following steps are taken leading +up to each release: + +1. 1 week before release date, update the release project board and alert + project contributors of upcoming release on slack. +2. For major releases or substantial features, optionally extend the release cycle, + if needed, so that the changes can be completed and incorporated in the release. + If a release will be delayed, notify project contributors on slack. +3. All changes to the main branch of the repository are frozen 1 day prior to the + release. At this point only the release managers (for this release) should + merge any pull requests. Remind core developers of the timing of the feature + freeze on slack when announcing the upcoming release date. Remind core developers + of the feature freeze again 1 day prior to its start. Make sure to keep + core developers in the loop if any delays or extensions to the feature freeze arise. +4. If "must have" pull requests are not merged by the planned release date, the + release manager should coordinate with the Steering Committee to either delay + the release date and extend freeze period, or move the pull requests target + completion to a later release. + +.. _release_version_prep: + +Preparing the release version +----------------------------- + +The release process is as follows, on high-level: + +1. Ensure deprecation actions are carried out. Deprecation actions for a version + should be marked by "version number" annotated comments in the code. E.g., + for the release 0.2.0, search for the string 0.2.0 in the code and carry out + the described deprecation actions. Collect list of deprecation actions in an issue, + as they will have to go in the release notes. Deprecation actions should be merged + only by release managers. + +2. Create a "release" Pull Request from a branch following the naming pattern + ``release-vm.x.y``, where "m", "x" and "y" are placeholders for the major, + minor, and patch version numbers. This pull request should: + + - Update the package version numbers + (see :ref:`version number locations `) + - Add complete release notes + (see :ref:`generating release notes `) + - Update the ``switcher.json`` file located at ``./docs/source/_static/`` + relative to the project's root. This involves creating a new entry for the + prior release (which was the "stable" doc release previously) and rename + the stable release to reference the updated version number. + +3. The PR and release notes should be reviewed by the other core developers, + then merged once tests pass. + +4. Create a GitHub draft release with a new tag following the syntax + v[MAJOR].[MINOR].[PATCH]. E.g., the string ``v0.12.0`` for version 0.12.0. + The GitHub release notes should contain only "new contributors" and + "all contributors" section, and otherwise link to the release notes in the + changelog, following the pattern of current GitHub release notes. + +.. _pypi_release: + +``pypi`` release and release validation +--------------------------------------- + +5. Publish the GitHub draft release. Creation of the new tag will trigger the + ``pypi`` release CI/CD. + +6. Wait for the ``pypi`` release CI/CD to finish. If tests fail due to sporadic + failures unrelated to the content being released, restart the CI/CD routine. + If tests fail genuinely, something went wrong in the above steps, investigate, + fix, and repeat. Common possibilities are core devs not respecting the feature + freeze period, new releases of dependencies that happen in the period between + release PR and release. + +7. Once release CI/CD has passed, check the ``predictably`` version on ``pypi``, + this should be the new version. It should be checked that all wheels have been + uploaded, `here `__. As a test, one install + of ``predictably`` in a new ``python`` environment should be carried out + according to the install instructions (choose an arbitrary version/OS). + If the install does not succeed or wheels have not been uploaded, urgent + action to diagnose and remedy must be taken. All core developers should be + informed of the situation through the contact all functionality in the + core developer channel on slack. In the most common case, the install + instructions need to be updated. If wheel upload has failed, the tag in Step 5 + needs to be deleted and recreated. The tag can be deleted using the + ``git`` command ``git push --delete origin tagname`` from a local repo. + +.. _conda_release: + +``conda`` release and release validation +---------------------------------------- + +8. If the release on ``pypi`` has succeeded, there should be an automated + release PR created against the ``predictably`` conda-forge repo: + https://github.com/conda-forge/predictably-feedstock. + + .. note:: Manual creation of release pull request + In cases where the release PR is not created automatically it can be created + and submitted manually. For general guidelines related to maintaining conda + feedstcok packages see + `conda-forge package `_. + + After forking and cloning the repo, edit the ``meta.yml`` file by: + + - incrementing the version in the line that contains ``{% set version = "M.X.Y" %}`` + - pasting the sha256 sum of the source archive from github in the + ``source/sha256`` section + + Once finished, submit the PR and ask for review. + +9. The conda release PR needs to be reviewed and in dependencies should be + checked against any changes in the main ``predictably`` repo. In case the + dependencies (or python version support) have changes, the ``meta.yml`` file + in the conda recipe needs to be updated to reflect those changes. + +10. Once reviewed, the conda release PR should merged, and it will automatically + trigger a release of the conda package. + +11. After 1h, it should be checked whether the package has been released on conda. + Once the package is available on ``conda``, a test install should be carried out + to validate the release. Should either of these fail, alert the core developers + and follow an urgent action plan in line with the description in step 7. + +.. _version_number_locs: + +Release Pull Request Tips +========================= + +When creating the release Pull Request it is important to update all the version +numbers and the release notes documentation. A full list of things that need to be +updated in every release Pull Request is contained below. It is possible a given +release could require more items to be updated. + +Version number locations +------------------------ + +Version numbers need to be updated in: + +* root ``__init__.py`` +* ``README.md`` +* ``pyproject.toml`` + +Add new choice to "switcher" +---------------------------- + +A new entry has to be added to the "switcher" that controls the drop down that +lets users see the documentation for different versions of the package. This is +done using the file ``predictably/docs/source/_static/switcher.json``. + +- Copy the entry for the current "stable" version and add it to the list (in + release order). +- Update the name of the copied entry to remove the "(stable)" terminology. +- Update the original "stable" version to update the version number in the + name and the url. + +Note that the "switcher" functionality doesn't work in the version of the docs that +is built during a Pull Request, so be sure to double-check you provided the right +version numbers. + +.. _generate_release_notes: + +Generating release notes +------------------------ + +Release notes can be generated using the ``build_tools.changelog.py`` script, +and should be placed at the top of the ``changelog.rst``. Generally, release notes +should follow the general pattern of previous release notes, with sections: + +* highlights +* dependency changes, if any +* deprecations and removals, if any. In PATCH versions, there are no deprecation + actions, but there can be new deprecations. + Deprecation action usually happen with the MINOR release cycle. +* core interface changes, if any. This means, changes to the base class interfaces. + Only MINOR or MAJOR releases should have core interface changes that are not + downwards compatible. +* enhancements, by module/area +* bugfixes +* documentation +* maintenance +* all contributor credits diff --git a/docs/source/get_involved/reviewer_guide.rst b/docs/source/get_involved/reviewer_guide.rst new file mode 100644 index 0000000..f3c2a4d --- /dev/null +++ b/docs/source/get_involved/reviewer_guide.rst @@ -0,0 +1,70 @@ +.. _reviewer_guide: +.. _rev_guide: + +============== +Reviewer Guide +============== + +Pull Request reviewers play an important role in ``predictably``'s development. On +the ``predictably`` project our review takes three main forms: + +- Triage +- Code Review +- Documentation Review + +See the details on each level of review below. + +.. warning:: + + The reviewer guide is under development. If you have suggestions, open an + issue or Pull Request. + + +Triage +====== + +* Assign relevant labels +* Assign to relevant project board +* Title: Is it using the 3-letter codes? Is it understandable? +* Description: Is it understandable? Any related issues/PRs? +* CI checks: approval for first-time contributors, any help needed with + code/doc quality checks? +* Merge conflicts + +Code Review +=========== + +* Unit testing: + + - Are the code changes tested? + - Are the tests understandable? + - Are all changes covered by tests? We usually aim for a test coverage of + at least 90% (but preferably 100% coverage on new code). + - Code coverage will be reported as part of the automated CI checks on + GitHub and on the + `Codecov website `_. + +* Test changes locally: Does everything work as expected? +* Deprecation warnings: + + - Has the public API changed? + - Have deprecation warnings been added before making the changes? + +.. _reviewer_guide_doc: + +Documentation Review +==================== + +* Are the docstrings complete and understandable to users? +* Do they follow the NumPy format and ``predictably`` conventions? +* If the same parameter, attribute, return object or error is included elsewhere + in ``predictably`` are the docstring descriptions as similar as possible? +* Does the online documentation render correctly with the changes? +* Do the docstrings contain links to the relevant topics in the + :ref:`glossary` or :ref:`user_guide`? + +.. note:: + + If a Pull Request does not meet ``predictably``'s + :ref:`documentation guide ` a reviewer should + require the documentation be updated prior to approving the Pull Request. diff --git a/docs/source/get_involved/testing_framework.rst b/docs/source/get_involved/testing_framework.rst new file mode 100644 index 0000000..7f0bfae --- /dev/null +++ b/docs/source/get_involved/testing_framework.rst @@ -0,0 +1,42 @@ +================= +Testing Framework +================= + +.. note:: + + This page will explain ``predictably``'s testing framework with an emphasis on + how contributors should use the framework to test their contributions. It is + a work in progress. + +``predictably`` uses ``pytest`` to verify code is working as expected. +This page gives an overview of the tests, an introduction on adding new tests, +and how to extend the testing framework. + +.. warning:: + + This page is under construction. We plan to add more tests and increased + documentation on the testing framework in an upcoming release. + +Test module architecture +======================== + +``predictably`` uses a tiered approach to test its functionality: + +- *package level* tests are located in ``predictably/tests/`` and are meant to + test functionality used throughout the package. + +- *module level* tests are included in the ``tests`` folders in each module and + are focused on verifying an individual models functionality. + +- *low level* tests in the ``tests`` folders in each module are used to verify the + functionality of individual code artifacts + +Module conventions are as follows: + +* Each module contains a ``tests`` folder that contains tests specific to that module. + * Sub-modules may also contain ``tests`` folders. + * *module* tests focused on testing a specific class interface should contain a file + ``test_all_[name_of_class].py`` +* ``tests`` folders may contain ``_config.py`` files to collect test + configuration settings for that modules. +* *module* and *low* level tests should not repeat tests performed at a higher level. diff --git a/docs/source/get_started.rst b/docs/source/get_started.rst new file mode 100644 index 0000000..9923e4d --- /dev/null +++ b/docs/source/get_started.rst @@ -0,0 +1,111 @@ +.. _getting_started: + +=========== +Get Started +=========== + +The following information is designed to get users up and running with +``predictably_core`` quickly. Links to additional details are provided +in each of the subsections below. + +Installation +============ + +``predictably_core`` currently supports: + +- environments with python version 3.8, 3.9, 3.10, 3.11 or 3.12 +- Common linux, Mac OS, and Windows operating systems + +Users can install ``predictably_core`` from PyPi using ``pip`` or using ``conda`` +to install the package from the conda-forge channel by using one of the code +snippets below. + +.. tab-set:: + + .. tab-item:: PyPi + + .. code-block:: bash + + pip install -U predictably-core + + .. tab-item:: Conda + + .. note:: + + We are still working on creating releases of ``predictably_core`` + on ``conda``. If you would like to help, please open a pull request. + +For additional details see our :ref:`full installation guide `. + +Key Concepts +============ + +``predictably_core``'s goal is to provide a :term:`framework` for building +packages that follow `scikit-learn`_, and `sktime`_ style design patterns. + +It takes inspiration from `skbase`_, but in some cases has made different design +choices. + +``predictably_core`` provides base classes (:class:`BaseObject` +and :class:`BaseEstimator`) with interfaces for: + +- `scikit-learn`_ style parameter getting and setting +- using :term:`tags ` to record characteristics of the class that can + be used to alter the classes code or how it interacts with other functionality + +``predictably_core`` also contains additional functionality to make it easy to +:term:`Python packages ` that provide build :term:`toolboxes ` +on top of the ``predictably_core`` design interface. This functionality includes: + +- retrieving information on ``BaseObject``-s +- performing type validations, including validating ``BaseObject``-s or + collections of ``BaseObject``-s + +Quickstart +========== +The code snippets below are designed to introduce ``predictably_core``'s +functionality. For more detailed information see the :ref:`user_guide` and +:ref:`api_ref` in ``predictably_core``'s :ref:`user_documentation`. + +Create a New Class Built on Top of ``BaseObject`` +------------------------------------------------- + +.. code-block:: pycon + + >>> from predictably_core.core import BaseObject + >>> class SomeClass(BaseObject): + ... """Some class docstring.""" + ... def __init__(self, some_param: int = 7): + ... self.some_param = some_param + ... + >>> some_class = SomeClass() + >>> some_class + SomeClass(some_param=7) + >>> some_class.get_params() + {'some_param': 7} + + +Define a New Class Using ``BaseObject`` and ``attrs`` +----------------------------------------------------- + +.. blacken-docs:off +.. code-block:: pycon + + >>> import attrs + >>> from predictably_core.core import BaseObject + # To use predictably_core's repr functionality make sure to disable attrs + # standard repr functionality + >>> @attrs.define(kw_only=True, repr=False) + >>> class SomeClass(BaseObject): + ... """Some class docstring.""" + ... some_param: int = 7 + >>> some_class = SomeClass() + >>> some_class + SomeClass(some_param=7) + >>> some_class.get_params() + {'some_param': 7} +.. blacken-docs:on + +.. _scikit-learn: https://scikit-learn.org/stable/index.html +.. _sktime: https://www.sktime.net/en/stable/index.html +.. _skbase: https://skbase.readthedocs.io/en/latest/index.html diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..4a7efd2 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,69 @@ +.. _home: + +=========================== +Welcome to predictably_core +=========================== + +``predictably_core``'s goal is to make it easier to build Python packages. It includes +classes the make it easy to reuse `scikit-learn`_, and `sktime`_ style design patterns. +It also includes common tools that make building packages easier. Explore the +rest of the documentation to learn more. + +.. toctree:: + :maxdepth: 1 + :hidden: + + get_started + users + api_reference + get_involved + about + changelog + +.. grid:: 1 2 2 2 + :gutter: 3 + + .. grid-item-card:: Get Started + :text-align: left + :link: get_started + :link-type: doc + + Get started with ``predictably_core`` quickly. + + .. grid-item-card:: User Documentation + :text-align: left + :link: users + :link-type: doc + + Find user documentation. + + .. grid-item-card:: API Reference + :text-align: left + :link: api_reference + :link-type: doc + + Understand ``predictably_core``'s API. + + .. grid-item-card:: Get Involved + :text-align: left + :link: get_involved + :link-type: doc + + Find out how you can contribute. + + .. grid-item-card:: About + :text-align: left + :link: about + :link-type: doc + + Learn more about ``predictably_core``. + + .. grid-item-card:: Release Notes + :text-align: left + :link: changelog + :link-type: doc + + See what's new in our latest release. + +.. _scikit-learn: https://scikit-learn.org/stable/index.html +.. _sktime: https://www.sktime.net/en/stable/index.html diff --git a/docs/source/user_documentation/changelog.rst b/docs/source/user_documentation/changelog.rst new file mode 100644 index 0000000..958ce91 --- /dev/null +++ b/docs/source/user_documentation/changelog.rst @@ -0,0 +1,24 @@ +========= +Changelog +========= + +This file will track changes in each version of ``predictably_core``. + +``predictably_core`` uses `Semantic Versioning `_ +for its releases and each releases changes will be documented based on the +`Keep a Changelog `_ format. + +The source code for all +`releases `_ is +available on GitHub. You can also subscribe to ``predictably_core``'s +`PyPi release `_. + +For planned changes and upcoming releases, see our :ref:`roadmap`. + +[0.1.0] - 2024-08-24 +==================== + +Highlights +---------- + +- Initial release of the ``predictably_core`` package! diff --git a/docs/source/user_documentation/glossary.rst b/docs/source/user_documentation/glossary.rst new file mode 100644 index 0000000..3326827 --- /dev/null +++ b/docs/source/user_documentation/glossary.rst @@ -0,0 +1,51 @@ +.. _glossary: + +======================== +Glossary of Common Terms +======================== + +The glossary below defines common terms and API elements used throughout +``predictably_core``. + +.. glossary:: + :sorted: + + Framework + A collection of related and reusable software design templates that + practitioners can copy and fill in. Frameworks emphasize design reuse. + They capture common software design decisions within a given application domain + and distill them into reusable design templates. This reduces the design + decision they must take, allowing them to focus on application specifics. + Not only can practitioners write software faster as a result, but + applications will have a similar structure. Frameworks often offer + additional functionality like :term:`toolboxes `. Compare with + :term:`toolbox` and :term:`application`. + + Toolbox + A collection of related and reusable functionality that practitioners + can import to write applications. Toolboxes emphasize code reuse. + Compare with :term:`framework` and :term:`application`. + + Application + A single-purpose piece of code that practitioners write to solve a + particular applied problem. Compare with :term:`toolbox` and :term:`framework`. + + Python module + According to Python's documentation a module is *"a file containing Python + definitions and statements"*. Python modules are files whose name is the + module name and the suffix is ".py". For more information see Python's + `documentation `_ + + Python namespace + According to Python's documentation a namespace is *"a mapping from names + to objects"*. For more information see Python's + `documentation `_ + + Python package + Python packages are a way to structure a collection of + :term:`Python modules ` into a single "namespace". Commonly + this is accomplished by having a directory that contains an ``__init__.py`` + file and one or more Python modules. The name of the directory, then becomes + the "package" namespace for the sub-modules it contains. For more information + see Python's + `documentation `_ diff --git a/docs/source/user_documentation/installation.rst b/docs/source/user_documentation/installation.rst new file mode 100644 index 0000000..c874c1b --- /dev/null +++ b/docs/source/user_documentation/installation.rst @@ -0,0 +1,55 @@ +.. _full_install: + +============ +Installation +============ + +``predictably_core`` currently supports: + +- environments with python version 3.8, 3.9, 3.10, 3.11 or 3.12 +- Common linux, Mac OS, and Windows operating systems + +Checkout the full list of pre-compiled wheels on `PyPI`_. + +Install a Release from PyPi or conda-forge +========================================== + +Most users will be interested in installing a released version of ``predictably_core``. +These can be installed from PyPi using ``pip`` or using ``conda`` to install the +package from the conda-forge channel by using one of the code snippets below. + +.. tab-set:: + + .. tab-item:: PyPi + + .. code-block:: shell + + pip install -U predictably-core + + .. tab-item:: Conda + + .. note:: + + We are still working on creating releases of ``predictably_core`` + +Install the Development Version from Github +=========================================== + +You can always use ``pip`` to install the latest version of ``predictably_core`` with +any new features and bug-fixes directly from the `Github repository`_: + +.. code-block:: shell + + pip uninstall predictably-core + pip install -U git+https://github.com/predictably/predictably-core.git@main + + +Developer Installation +====================== + +If you plan to contribute to ``predictably_core`` you'll want to follow our +:ref:`development installation instructions ` that are included in +our :ref:`development guide `. + +.. _Github repository: https://github.com/predict-ably/predictably-core +.. _PyPi: https://pypi.org/simple/predictably-core/ diff --git a/docs/source/user_documentation/user_guide.rst b/docs/source/user_documentation/user_guide.rst new file mode 100644 index 0000000..2cda85d --- /dev/null +++ b/docs/source/user_documentation/user_guide.rst @@ -0,0 +1,45 @@ + +.. _user_guide: + +========== +User Guide +========== + +Welcome to ``predictably_core``'s user guide! + +The purpose of the user guide is to provide additional information on how to +use ``predictably_core``'s functionality in your project. + +If your just looking for a technical specification of the functionality +that ``predictably_core`` provides, see the :ref:`api_ref`. + +.. note:: + + The user guide is under development. We have created a basic + structure and are looking for contributions to develop the user guide + further. + +.. toctree:: + :maxdepth: 1 + :hidden: + + user_guide/overview + user_guide/configuration + + +.. grid:: 1 2 2 2 + :gutter: 3 + + .. grid-item-card:: Overview + :text-align: left + :link: user_guide/overview + :link-type: doc + + Get an overview of ``predictably_core``'s interfaces and design patterns. + + .. grid-item-card:: Configuration + :text-align: left + :link: user_guide/configuration + :link-type: doc + + Learn how you can configure ``predictably_core``. diff --git a/docs/source/user_documentation/user_guide/configuration.rst b/docs/source/user_documentation/user_guide/configuration.rst new file mode 100644 index 0000000..b3dcc4a --- /dev/null +++ b/docs/source/user_documentation/user_guide/configuration.rst @@ -0,0 +1,11 @@ +.. _user_guide_global_config: + +============================== +Configure ``predictably_core`` +============================== + +.. note:: + + The user guide is under development. We have created a basic + structure and are looking for contributions to develop the user guide + further. diff --git a/docs/source/user_documentation/user_guide/overview.rst b/docs/source/user_documentation/user_guide/overview.rst new file mode 100644 index 0000000..147dc8d --- /dev/null +++ b/docs/source/user_documentation/user_guide/overview.rst @@ -0,0 +1,11 @@ +.. _user_guide_overview: + +================================ +Overview of ``predictably_core`` +================================ + +.. note:: + + The user guide is under development. We have created a basic + structure and are looking for contributions to develop the user guide + further. diff --git a/docs/source/users.rst b/docs/source/users.rst new file mode 100644 index 0000000..cc60e17 --- /dev/null +++ b/docs/source/users.rst @@ -0,0 +1,46 @@ +.. _user_documentation: + +================== +User Documentation +================== + +.. toctree:: + :maxdepth: 1 + :hidden: + + user_documentation/installation + user_documentation/user_guide + user_documentation/glossary + user_documentation/changelog + + +.. grid:: 1 2 2 2 + :gutter: 3 + + .. grid-item-card:: Installation + :text-align: left + :link: user_documentation/installation + :link-type: doc + + Install ``predictably_core``. + + .. grid-item-card:: User Guide + :text-align: left + :link: user_documentation/user_guide + :link-type: doc + + Dig into the details of using ``predictably_core``. + + .. grid-item-card:: Glossary + :text-align: left + :link: user_documentation/glossary + :link-type: doc + + Understand common terminology. + + .. grid-item-card:: Release Notes + :text-align: left + :link: user_documentation/changelog + :link-type: doc + + See what's new in our latest release. diff --git a/predictably_core/core/__init__.py b/predictably_core/core/__init__.py index 2c0d21d..f201c92 100644 --- a/predictably_core/core/__init__.py +++ b/predictably_core/core/__init__.py @@ -1,8 +1,8 @@ #!/usr/bin/env python3 -u # copyright: predict-ably, BSD-3-Clause License (see LICENSE file) -""":mod:`predictably._core` includes core functionality used to build `predictably`. +""":mod:`predictably_core.core` provides building blocks for the `predicably` framework. -These tools can be used to build other `predictably` compliant packages. +These tools can be used to build other `predictably` style packages. """ from __future__ import annotations diff --git a/predictably_core/utils/__init__.py b/predictably_core/utils/__init__.py index 2784299..454f428 100644 --- a/predictably_core/utils/__init__.py +++ b/predictably_core/utils/__init__.py @@ -3,7 +3,7 @@ # Elements of predictably.utils reuse code developed for skbase. These elements # are copyrighted by the skbase developers, BSD-3-Clause License. For # conditions see https://github.com/sktime/skbase/blob/main/LICENSE -""":mod:`predictably.utils` includes utility functionality used through `predictably`. +""":mod:`predictably_core.utils` includes utilities used in the `predictably` framework. This module includes general utilities. """