Skip to content

Commit

Permalink
From refs/pull/106/merge 68fdba1
Browse files Browse the repository at this point in the history
  • Loading branch information
@ns-rse
ns-rse committed Dec 10, 2024
0 parents commit c5a5370
Show file tree
Hide file tree
Showing 66 changed files with 9,254 additions and 0 deletions.
Empty file added .nojekyll
Empty file.
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
#GitHub Pages

Last update of sphinx html documentation from [68fdba1](https://github.com/sudlab/IsoSLAM/tree/68fdba15331c69e784e9ef1598279772cf692d91)
8 changes: 8 additions & 0 deletions index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<!DOCTYPE html>
<html>
<head>
<title>Redirecting to main branch</title>
<meta http-equiv="refresh" content="0; url=./main/index.html">
<link rel="canonical" href="https://sudlab.github.io/IsoSLAM/main/index.html">
</head>
</html>
4 changes: 4 additions & 0 deletions main/.buildinfo
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 7fb97b73c1dadc812597ac67dfae4465
tags: 645f666f9bcd5a90fca523b33c5a78b7
Binary file added main/.doctrees/autoapi/conf/index.doctree
Binary file not shown.
Binary file added main/.doctrees/autoapi/index.doctree
Binary file not shown.
Binary file added main/.doctrees/contributing.doctree
Binary file not shown.
Binary file added main/.doctrees/environment.pickle
Binary file not shown.
Binary file added main/.doctrees/index.doctree
Binary file not shown.
Binary file added main/.doctrees/installation.doctree
Binary file not shown.
Binary file added main/.doctrees/introduction.doctree
Binary file not shown.
Binary file added main/.doctrees/usage.doctree
Binary file not shown.
Binary file added main/.doctrees/workflow.doctree
Binary file not shown.
Empty file added main/.nojekyll
Empty file.
157 changes: 157 additions & 0 deletions main/_sources/autoapi/conf/index.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
conf
====

.. py:module:: conf
Attributes
----------

.. autoapisummary::

conf.autodoc_mock_imports
conf.project
conf.copyright
conf.author
conf.release
conf.version
conf.extensions
conf.templates_path
conf.html_sidebars
conf.source_suffix
conf.master_doc
conf.language
conf.exclude_patterns
conf.pygments_style
conf.myst_heading_anchors
conf.html_theme
conf.html_static_path
conf.html_css_files
conf.htmlhelp_basename
conf.latex_elements
conf.latex_documents
conf.man_pages
conf.texinfo_documents
conf.epub_title
conf.epub_exclude_files
conf.numpydoc_class_members_toctree
conf.autoapi_dirs
conf.smv_tag_whitelist
conf.smv_branch_whitelist
conf.smv_released_pattern
conf.smv_outputdir_format


Module Contents
---------------

.. py:data:: autodoc_mock_imports
:value: ['numpy', 'pandas', 'matplotlib', 'seaborn', 'scipy', 'skimage']


.. py:data:: project
:value: 'IsoSLAM'


.. py:data:: copyright
:value: '2024, IsoSLAM authors'


.. py:data:: author
:value: 'IsoSLAM authors'


.. py:data:: release
.. py:data:: version
:value: ''


.. py:data:: extensions
:value: ['autoapi.extension', 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages',...


.. py:data:: templates_path
:value: ['_templates']


.. py:data:: html_sidebars
.. py:data:: source_suffix
.. py:data:: master_doc
:value: 'index'


.. py:data:: language
:value: 'en'


.. py:data:: exclude_patterns
:value: ['_build', 'Thumbs.db', '.DS_Store']


.. py:data:: pygments_style
:value: None


.. py:data:: myst_heading_anchors
:value: 3


.. py:data:: html_theme
:value: 'pydata_sphinx_theme'


.. py:data:: html_static_path
:value: ['_static']


.. py:data:: html_css_files
:value: ['custom.css']


.. py:data:: htmlhelp_basename
:value: 'IsoSLAMdoc'


.. py:data:: latex_elements
.. py:data:: latex_documents
.. py:data:: man_pages
.. py:data:: texinfo_documents
.. py:data:: epub_title
:value: 'IsoSLAM'


.. py:data:: epub_exclude_files
:value: ['search.html']


.. py:data:: numpydoc_class_members_toctree
:value: False


.. py:data:: autoapi_dirs
:value: ['../']


.. py:data:: smv_tag_whitelist
:value: '^v\\d+.*$'


.. py:data:: smv_branch_whitelist
:value: '^(main)$'


.. py:data:: smv_released_pattern
:value: '^tags/.*$'


.. py:data:: smv_outputdir_format
:value: '{ref.name}'


11 changes: 11 additions & 0 deletions main/_sources/autoapi/index.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
API Reference
=============

This page contains auto-generated API reference documentation [#f1]_.

.. toctree::
:titlesonly:

/autoapi/conf/index

.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_
195 changes: 195 additions & 0 deletions main/_sources/contributing.md.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
# Contributing

This document describes how to contribute to the development of this software.

## Bug Reports

If you find a but we need to know about it so we can fix it. Please report your [bugs on our GitHub Issues
page][gh-bug].

## Feature Requests

If you find IsoSLAM useful but think it can be improved you can [make a feature request][gh-feature].

## Code Contributions

If you would like to fix a bug or add a new feature that is great, Pull Requests are very welcome.

However, we have adopted a number of good software development practises that ensure the code and documentation is
linted and that unit and regression tests pass both locally and on Continuous Integration. The rest of this page helps
explain how to set yourself up with these various tools.

## Virtual Environments

Use of [virtual environments][venv], particularly during development of Python packages, is encouraged. There are lots of
options out there for you to choose from including...

- [Miniconda][miniconda]
- [venv][venv]
- [virtualenvwrapper][virtualenvwrapper]

Which you choose is up to you, although you should be wary of using the [Miniconda][miniconda] distribution from
[Anaconda][anaconda] if any of your work is carried out for or in conjunction with a commercial entity.

### uv

Developers are using the [uv][uv] package manager to setup and control environments to which end a [`uv.lock`][uv-lock]
file is included in the repository. [uv][uv] supports managing virtual environments so you may wish to install and use
this tool at the system level to manage your virtual environments for this package.

## Cloning the Repository

Once you have setup your virtual environment you should clone the repository from GitHub

```bash
cd ~/path/you/want/to/clone/to
git clone https://github.com/sudlab/IsoSLAM
```

### Install development

Once you have clone the IsoSLAM repository you should install all the package along with all development and
documentation dependencies in "editable" mode. This means you can test the changes you make in real time.

```bash
cd IsoSLAM
pip install --no-cache-dir -e .[docs,dev]
```

## Git

[Git][git] is used to version control development of the package. The `main` branch on GitHub and the [pre-commit
hooks](contributing#pre-commit) have protections in place that prevent committing/pushing directly to the `main`
branch. This means you should create a branch to undertake development or fix bugs.

### Issues

Ideally an [issue][isoslam-issue] should have been created detailing the feature request. If it is a large amount of
work this should be captured in an issue labelled "_Epic_" and the steps taken to achieve all work broken down into
smaller issues.

### Branch nomenclature

When undertaking work on a particular issue it is useful to use informative branch names. These convey information about
what the branch is for beyond simply "`adding-feature-x`". You should create the branch using your GitHub username,
followed by the issue number and a short description of the work being undertaken. For example
`ns-rse/31-merge-slam-3uis` as this allows others to know who has been undertaking the work, what issue the work relates
to and has an informative name as to the nature of that work.

## Linting

[Linting][linting] is the practice of following a consistent coding style. For Python that style is defined in
[PEP8][pep8]. By following a consistent style across a code base it is easier to read and understand the code written by
others (including your past self!). We use the following linters implemented as [pre-commit](#pre-commit) hooks

- Python
- [Black][black]
- [Blacken-docs][blacken-docs]
- [flake8][flake8]
- [Numpydoc][numpydoc-validation]
- [Ruff][ruff]
- Other
- [Codespell][codespell] (Spelling across all filesyy)
- [markdownlint-cli2][markdownlint-cli2] (Markdown)
- [prettier][prettier] (Markdown, YAML)

## Pre-commit

Style checks are made using the [pre-commit][pre-commit] framework which is one of the development dependencies and
should have been installed in the previous step. You can check if its is installed in your virtual environment with `pip
show pre-commit`. If you have pre-commit installed install the hook using...

```bash
pre-commit install
```

This adds a file to `.git/hooks/pre-commit` that will run all of the hooks specified in `.pre-commit-config.yaml`. The
first time these are run it will take a little while as a number of virtual environments are downloaded for the first
time. It might be a good time to run these manually on the code base you have just cloned which should pass all checks.

```bash
pre-commit run --all-files
```

These should all pass. Now whenever you try to make a `git commit` these checks will run _before_ the commit is made and
if any fail you will be advised of what has failed. Some of the linters such as [Black][black] and [Ruff][ruff] will
automatically correct any errors that they find and you will have to stage the files that have changed again. Not all
errors can be automatically corrected (e.g. [Numpydoc validation][numpydoc-validation] and [Pylint][pylint]) and you
will have to manually correct these.

## Docstrings

It is sensible and easiest to write informative docstrings when first defining your modules, classes and
methods/functions. Doing so is a useful _adie-memoire_ not only for others but your future self and with modern Language
Servers that will, on configuration, show you the docstrings when using the functions it helps save time.

You will find your commits fail the [numpydoc-validation][numpydoc-validation] pre-commit hook if you do not write
docstrings and will be prompted to add one.

## Testing

We use the [pytest][pytest] framework with various plugins in our testing suite. When correcting bugs and adding
features at a bare minimum the existing tests should not fail. Where possible we would be grateful of contributions to
the test suite. This means if an edge case has been identified and a solution derived a test is added that checks the
edge case is correctly handled. For new features would ideally mean writing [unit-tests][unit-tests] to ensure each
function or method works as intended and for larger classes that behaviour is as expected. Sometimes tests will need
updating in light of bug fixes and features which is to be expected, but remember to commit updates to tests as well as
to code to ensure the Continuous Integration tests pass.

### Pytest-testmon

To shorten the feedback loop during development the [pytest-testmon][pytest-testmon] plugin is used as a
[pre-commit](#pre-commit) hook so that only the tests affected by the changes that are being committed are run. This
requires that on first installing the package you create a local database of the state of the tests by running the
following...

```bash
pytest --test-mon
```

This creates the files `.testmondata` which stores the current state of tests. Once created commits will only run
affected tests. However if your environment has changed, such as adding new packages or updating installed packages you
will have to recreate the database.

## Pull Requests

Once you have made your changes and committed them you will at some point wish to make a [Pull Request][gh-pr] to merge
them into the `main` branch.

In order to keep Git history clean and easier to understand you can perform an interactive [`git rebase -i`][git-rebase]
on your feature branch to squash related commits and tidy up your commit history.

When your branch is ready for merging with `main` open a [Pull Request][gh-pr]. You can use the [GitHub
keywords][gh-keywords] of `close[s|d]`/`fix[es|ed]` / `resolve[s|d]` followed by the issue number in the body of your
commit message which will change the status of the issue to "_Closed_" when the Pull Request is merged.

Pull Requests will be reviewed in a timely and hopefully constructive manner.

[anaconda]: https://www.anaconda.com/blog/update-on-anacondas-terms-of-service-for-academia-and-research
[black]: https://black.readthedocs.io/en/stable/index.html
[blacken-docs]: https://github.com/adamchainz/blacken-docs
[codespell]: https://github.com/codespell-project/codespell
[flake8]: https://flake8.pycqa.org/en/latest/
[gh-bug]: https://github.com/sudlab/IsoSLAM/issues/new?assignees=&labels=bug&projects=sudlab%2F1&template=bug_report.yaml&title=%5Bbug%5D%3A+
[gh-feature]: https://github.com/sudlab/IsoSLAM/issues/new?assignees=&labels=enhancement&projects=sudlab%2F1&template=feature_request.yaml&title=%5Bfeature%5D+%3A+
[gh-keywords]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests
[gh-pr]: https://github.com/sudlab/IsoSLAM/pulls
[isoslam-issue]: https://github.com/sudlab/IsoSLAM/issues/
[git]: https://git-scm.com
[git-rebase]: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
[linting]: https://en.wikipedia.org/wiki/Lint_(software)
[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2
[miniconda]: https://docs.anaconda.com/miniconda/
[numpydoc-validation]: https://numpydoc.readthedocs.io/en/latest/validation.html
[pep8]: https://peps.python.org/pep-0008/
[pre-commit]: https://pre-commit.com/
[prettier]: https://prettier.io/docs/en/
[pylint]: https://www.pylint.org/
[pytest]: https://pytest.org
[pytest-testmon]: https://pypi.org/project/pytest-testmon/
[ruff]: https://docs.astral.sh/ruff
[unit-tests]: https://en.wikipedia.org/wiki/Unit_testing
[uv]: https://docs.astral.sh/uv/
[uv-lock]: https://docs.astral.sh/uv/concepts/projects/#project-lockfile
[venv]: https://docs.python.org/3/library/venv.html
[virtualenvwrapper]: https://virtualenvwrapper.readthedocs.io/en/latest/
Loading

0 comments on commit c5a5370

Please sign in to comment.