[DOC] Update developer documentation (#2297)

* write local documentation dev guide * dev docs * dev docs * fixes * fixes * fix forecasting testing (they still fail though) --------- Co-authored-by: aadya940 <[email protected]>
aeon-toolkit · Nov 6, 2024 · 8107cc8 · 8107cc8
1 parent eadf286
commit 8107cc8
Show file tree

Hide file tree

Showing 13 changed files with 569 additions and 278 deletions.
diff --git a/docs/about.md b/docs/about.md
@@ -49,12 +49,20 @@ The core developers push forward `aeon`'s development and maintain the package.
 ```{include} about/core_developers.md
 ```
 
+## Affiliation
+
+`aeon` is an affiliated project of [NumFOCUS](https://numfocus.org/).
+
+![https://numfocus.org/](images/other_logos/numfocus-logo.png){w=300px}
+
 ## History
 
 `aeon` was started in January 2023 as a fork of the `sktime` project by 8 core
 developers using [v0.16.0](https://github.com/aeon-toolkit/aeon/releases/tag/sktime-v0.16.0)
-as a base. In following year, the project grew to include an additional 4 core
-developers and was accepted as a NumFOCUS affiliated project in December 2023.
+as a base. In the following years, the project has grown to include many more core
+developers, had a complete revamp of governance structure, and relaunched numerous
+modules for time series learning tasks. `aeon` was accepted as a NumFOCUS affiliated
+project in December 2023.
 
 ## Artwork
 
@@ -70,34 +78,63 @@ The logo was designed by [Reni Rahayu](https://www.instagram.com/kojodesignandco
 `aeon` is a community-driven project. However, institutional and private grants help to
 ensure its sustainability.
 
-The project developers would like to thank the following funders.
+The project developers would like to thank the following funders:
 
 ```{list-table}
 :widths: 50 50
 :header-rows: 1
 
 * -
   -
-* - The [UKRI Engineering and Physical Sciences Research Council (EPSRC)](https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/W030756/1) funds Matthew Middlehurst ({user}`matthewmiddlehurst`) and Tony Bagnall ({user}`TonyBagnall`) since 2022
+* - The [UKRI Engineering and Physical Sciences Research Council (EPSRC)](https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/W030756/1) funds Matthew Middlehurst ({user}`matthewmiddlehurst`) and Tony Bagnall ({user}`TonyBagnall`) between 2022-2025
   - ![https://epsrc.ukri.org](images/funder_logos/ukri-epsrc-logo.png)
 ```
 
+Short-term funding (<6 months) for internships has been provided by the following
+organisations:
+
+```{list-table}
+:header-rows: 1
+
+* - Name
+  - GitHub ID
+  - Organization
+  - Year
+* - Divya Tiwari
+  - {user}`itsdivya1309`
+  - [Google Summer of Code](https://summerofcode.withgoogle.com)
+  - 2024
+* - Aadya Chinubhai
+  - {user}`aadya940`
+  - [Google Summer of Code](https://summerofcode.withgoogle.com)
+  - 2024
+* - Gabriel Riegner
+  - {user}`griegner`
+  - [Google Summer of Code](https://summerofcode.withgoogle.com)
+  - 2024
+* - Ivan Knyazev
+  - {user}`IRKnyazev`
+  - [EPSRC](https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/W030756/1)
+  - 2024
+* - Daniele Carli
+  - {user}`Moonzyyy`
+  - [EPSRC](https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/W030756/1)
+  - 2024
+```
+
+Google Summer of Code (GSoC) sponsored internships applied and contributed to `aeon`
+projects via the shared NumFOCUS application for the program.
+
 ## Infrastructure
 
 We would also like to thank [GitHub Actions](https://github.com/features/actions)
 and [ReadtheDocs](https://readthedocs.org) for the free compute time on their servers
 and documentation hosting.
 
-## Affiliation
-
-`aeon` is an affiliated project of [NumFOCUS](https://numfocus.org/).
-
-![https://numfocus.org/](images/other_logos/numfocus-logo.png){w=300px}
-
 
 ## Pre-fork Acknowledgements
 
-<details><summary>sktime v0.16.0 core developers</summary>
+<details><summary>`sktime` v0.16.0 core developers</summary>
 <p>
 
 The following listed contributors were part of the `sktime` core developer team at some
@@ -127,7 +164,7 @@ point prior to the split of the project.
 </p>
 </details>
 
-<details><summary>sktime v0.16.0 funders</summary>
+<details><summary>`sktime` v0.16.0 funders</summary>
 <p>
 
 As a fork of the `sktime` project, `aeon` has benefited from funding given to `sktime`
@@ -143,13 +180,13 @@ prior to the projects split. We would like to thank the funders from before the
   - ![https://turing.ac.uk/](images/funder_logos/ati-logo.png)
 * - Markus Löning’s ({user}`mloning`) contributions between 2019 and 2021 were supported by the [UKRI Economic and Social Research Council (ESRC)](https://esrc.ukri.org), the [Consumer Data Research Centre (CDRC)](https://www.cdrc.ac.uk), the Enrichment Scheme at the [The Alan Turing Institute](https://turing.ac.uk), and the JROST Rapid Response Fund, a community effort of [Invest in Open Infrastructure](https://investinopen.org).
   - ![https://esrc.ukri.org](images/funder_logos/ukri-esrc-logo.png) ![https://www.cdrc.ac.uk](images/funder_logos/cdrc-logo.png) ![https://turing.ac.uk/](images/funder_logos/ati-logo.png)
-* - Mercedes-Benz AG/Daimler AG donated 2500 EUR to support the maintenance and development of sktime in 2021, as part of their [FOSS program](https://opensource.mercedes-benz.com).
+* - Mercedes-Benz AG/Daimler AG donated 2500 EUR to support the maintenance and development of `sktime` in 2021, as part of their [FOSS program](https://opensource.mercedes-benz.com).
   - ![https://opensource.mercedes-benz.com](images/funder_logos/mercedes-benz-logo.png)
 ```
 
 __Sprints__
 
-The 2019 joint sktime/MLJ development sprint was kindly hosted by
+The 2019 joint `sktime`/`MLJ` development sprint was hosted by
 [UCL](https://www.ucl.ac.uk) and [The Alan Turing Institute](https://turing.ac.uk).
 Some participants could attend thanks to the initial funding of the
 [The Alan Turing Institute](https://turing.ac.uk).
@@ -158,9 +195,9 @@ __Internships__
 
 [Google Summer of Code (GSoC)](https://summerofcode.withgoogle.com),
 [Major League Hacking](https://mlh.io) and [Outreachy](https://www.outreachy.org)
-have all sponsored sktime internships.
+have all sponsored `sktime` internships.
 
-The [Wellcome Trust](https://wellcome.org) sponsored one sktime internship as part of
+The [Wellcome Trust](https://wellcome.org) sponsored one `sktime` internship as part of
 Outreachy.
 
 ```{list-table}

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -40,7 +40,9 @@ address. If you are unsure about any feedback, please ask for clarification.
 making a contribution! Make sure you are included in the [list of contributors](contributors.md).
 
 Further guidance for contributing to `aeon` via GitHub can be found on the
-[developer guide](developer_guide.md).
+[developer guide](developer_guide.md). It is not necessary to read everything here prior to
+contributing, but if your issue to related to a specific topic i.e. documentation or
+testing you may find it useful.
 
 If your intended method of contribution does not fit into the above steps, please
 reach out to us on [Slack](https://join.slack.com/t/aeon-toolkit/shared_invite/zt-22vwvut29-HDpCu~7VBUozyfL_8j3dLA)
@@ -89,11 +91,11 @@ Developer Guide
 :::{grid-item-card}
 :text-align: center
 
-Reporting Bugs
+Opening Issues
 
 ^^^
 
-Guidance for reporting bugs in `aeon`.
+Guidance for issues and reporting bugs in `aeon`.
 
 +++
 
@@ -102,7 +104,7 @@ Guidance for reporting bugs in `aeon`.
 :click-parent:
 :expand:
 
-Reporting Bugs
+Opening Issues
 ```
 
 :::
@@ -132,5 +134,5 @@ Mentoring and Projects
 ```{toctree}
 :hidden:
 
-contributing/reporting_bugs.md
+contributing/issues.md
 ```
diff --git a/docs/contributing/reporting_bugs.md → docs/contributing/issues.md b/docs/contributing/reporting_bugs.md → docs/contributing/issues.md
@@ -1,4 +1,4 @@
-# Reporting Bugs and Opening Issues
+# Opening Issues and Reporting Bugs
 
 We use [GitHub issues](https://github.com/aeon-toolkit/aeon/issues) to track all bugs
 and feature requests; feel free to open an issue if you have found a bug or wish to see

diff --git a/docs/developer_guide.md b/docs/developer_guide.md
@@ -1,8 +1,8 @@
 # Developer Guide
 
 Welcome to the `aeon` developer guide. This guide is intended for new developers and
-current developers who want to learn about specific topics for code and non-code
-developments.
+current developers who want to learn about specific topics for both code and non-code
+project development.
 
 For a step-by-step guide for setting up a development version of `aeon`
 and creating a pull request, see the [contributing guide](contributing.md). At any point
@@ -20,24 +20,6 @@ their [developer's guide](https://scikit-learn.org/stable/developers/index.html)
 :::{grid-item-card}
 :text-align: center
 
-Adding Estimators
-
-^^^
-
-A guide to creating new `aeon` estimators.
-
-+++
-
-```{button-ref} developer_guide/add_estimators
-:color: primary
-:click-parent:
-:expand:
-
-Adding Estimators
-```
-
-:::
-
 :::{grid-item-card}
 :text-align: center
 
@@ -83,27 +65,6 @@ Coding Standards
 :::{grid-item-card}
 :text-align: center
 
-CI/CD
-
-^^^
-
-A description of the `aeon` CI/CD pipeline.
-
-+++
-
-```{button-ref} developer_guide/continuous_integration
-:color: primary
-:click-parent:
-:expand:
-
-CI/CD
-```
-
-:::
-
-:::{grid-item-card}
-:text-align: center
-
 Dependencies
 
 ^^^
@@ -232,14 +193,12 @@ Testing
 ```{toctree}
 :hidden:
 
-developer_guide/add_estimators.md
 developer_guide/aep.md
 developer_guide/coding_standards.md
-developer_guide/continuous_integration.md
 developer_guide/dependencies.md
 developer_guide/deprecation.md
 developer_guide/dev_installation.md
 developer_guide/documentation.md
 developer_guide/release.md
-developer_guide/testing_framework.md
+developer_guide/testing.md
 ```
diff --git a/docs/developer_guide/aep.md b/docs/developer_guide/aep.md
@@ -1,12 +1,12 @@
 # `aeon` Enhancement Proposals
 
-## Description
-
 An `aeon` enhancement proposal (AEP) is a software design document providing information
 to the aeon community. The proposal should provide a rationale and concise technical
 specification of the proposed design.
 
-We collect and discuss proposals in the `aeon` AEP [repository](https://github.com/aeon-toolkit/aeon-admin/tree/main/aep).
+We collect and discuss proposals in the `aeon` AEP [repository](https://github.com/aeon-toolkit/aeon-admin/).
+In-progress AEPs can be found in the [pull requests](https://github.com/aeon-toolkit/aeon-admin/pulls)
+section. Completed AEPs can be found [here](https://github.com/aeon-toolkit/aeon-admin/tree/main/aep).
 
 We intend AEPs to be the primary mechanisms for proposing major changes such as new
 modules and collecting community input on large or controversial issues. Smaller
@@ -24,3 +24,9 @@ consolidated document, including:
 * a concise problem statement,
 * a clear description of the proposed solution,
 * a comparison with alternative solutions.
+
+The AEP will remain open until the proposal is accepted or rejected. After being opened
+the proposal then can be implemented (possibly through multiple steps) through pull
+requests in the main repository. It is up to the core developers to determine when an
+AEP is  considered completed, in-progress or rejected. For items such as new modules,
+the AEP will be considered complete when the module is no longer experimental.
diff --git a/docs/developer_guide/coding_standards.md b/docs/developer_guide/coding_standards.md
@@ -37,11 +37,9 @@ Additional configurations for some hooks can be found in the [pyproject.toml](ht
 
 ### `aeon` specific code formatting conventions
 
-- Check out our [glossary](glossary.md) for
-preferred terminology
 - Use underscores to separate words in non-class names i.e.`n_cases` rather than
-`n_cases`.
-- Exceptionally, capital letters `X`, `Y`, `Z`, are permissible as variable names or
+`ncases`,  `nCases` or similar.
+- Exceptionally, capital letters i.e. `X` are permissible as variable names or
 part of variable names such as `X_train` if referring to data sets.
 - Use absolute imports for references inside `aeon`.
 - Don’t use `import *` in the source code. It is considered harmful by the official
@@ -59,7 +57,7 @@ clone:
 includes `pre-commit`:
 
 ```{code-block} powershell
-pip install -e .[dev]
+pip install --editable .[dev]
 ```
 
 2. Set up pre-commit:

diff --git a/docs/developer_guide/continuous_integration.md b/docs/developer_guide/continuous_integration.md