diff --git a/docs/source/customising.rst b/docs/source/customising.rst new file mode 100644 index 0000000..16f7910 --- /dev/null +++ b/docs/source/customising.rst @@ -0,0 +1,72 @@ +.. _customising-label: + +Preparing and customising your project +###################################### +Running the cookiecutter provides you with a skeleton for a Python package, +including configuration files for several optional tools. All generated files +live in a the ``{repo_name}`` directory. + +The next steps are to add your code, corresponding tests and documentation, +and complete any extra steps to get optional tools running (e.g. linking to +external services). The sections below provide more detail on these steps. +Generated file will be discussed as the become relevant; see +:ref:`files-label` for an overview of all the generated files. + +.. toctree:: + :maxdepth: 1 + + customising/github + customising/code + customising/tests + customising/documentation + customising/packaging + + +In addition to code and configuration files, the cookiecutter template +includes several ready-to-go human-readable files intended to provide +information to your users, contributors, or general community. Make sure to +read each though and see that it matches your vision for your project, or +ammend appropriately: + +.. _general-info: + +* **License:** Your code needs to be clearly licensed so that users know if + they can (legally) use it. The cookiecutter will apply the **GPLv2** + license by default, included in the ``LICENSE`` file. If you decide to use a + different license (see `ChooseALicense `_), also + update the copyright infromation in ``README.md``. + +* **README:** ``README.md`` is the introductory explanation to you project; it + will be rendered on your GitHub repo's home page. It has been pre-filled with + some basic information, including your description and several badges that + provide at-a-glance information to users on current version, test status, and more. + +.. _community-resources: + +**Community resources** + +* ``CODE_OF_CONDUCT.md`` outlines rules for behaviour for those in your community. +* ``CONTRIBUTING.md`` provides information and instructions for those who want to contribute. + + + +Add your package to the MDAKit Registry! +======================================== +The cookiecutter-generated template already ticks off most of the requirements +for registering your MDAKit on the `MDAKit Registry `_! + +Once you've added your code, tests, and added the package to GitHub, you should +be ready to start the `registration process `_ +(though it is recommended you continue to develop your package beyond these +basic requirements). + +.. _documenting-changes: + +Documenting changes going forward +================================= +An initial ``AUTHORS.md`` (pre-populated with your name) and tempate +``CHANGELOG.md`` are also generated. As you go forward and develop your code, +**update these files to track all contributors and important changes to your +project**. Instructions are provided within each file suggesting the appropriate +format to use. + diff --git a/docs/source/customising/code.rst b/docs/source/customising/code.rst new file mode 100644 index 0000000..d20b7a9 --- /dev/null +++ b/docs/source/customising/code.rst @@ -0,0 +1,68 @@ +Making and pushing changes to your code +======================================= + +.. _adding-code: + +Now you should go forth and code! + +Your project's code will live in the ``{package_name}/`` directory. +A basic ``__init__.py`` file (which :ref:`sets the version `) as +been pre-generated, along with several subpackages (and accompanying (empty) +``__init__.py``): + +* ``analysis/``: If you chose to include a template analysis class when + running the cookiecutter, that class will appear in + ``{package_name}/anaylsis/{template_analysis_class}.py``. This class is based + on `MDAnalysis AnalysisBase `_. + Comments in file should help you as you customise this class for your analysis. +* ``tests/``: where your code's unit tests will live. See :ref:`writing-tests`. + +* ``data/``: for including additional (non-code) files with your package, such + as molecular structures; this may be useful for e.g. running tests. The + included ``data/README.md`` file provides more information. ``files.py`` + provides an example of how to set up files so they can be imported elsewhere + in your package (useful especially if you wish to use the data in multiple + places), using the example datafile ``mda.txt``- containing ASCII art of the + MDAnalysis logo. The :ref:`example test files ` include an + example usage of this file. + + +Tips while writing your code +---------------------------- +To keep things clean and simple, we advise a few tips: + +.. _virtual-environment: + +* Always work in a virtual environment like ``conda``. + You can create a development environment by following + the instructions in the README. In short, to create an environment that should contain + all the tools you need to write and (locally) run tests and build documentation: + + + .. code-block:: bash + + conda create --name python=3.8 + conda activate # remember to do this every time + conda env update --name --file devtools/conda-envs/test_env.yaml + conda env update --name --file docs/requirements.yaml + + +* Always work in a separate branch. The ``main`` branch + is the default, or central, branch. All development + work should be done in a separate branch to avoid + messing up the main branch, or to allow you to work on + different approaches at the same time. This also + allows multiple people to work on the code at the same time. + Create a new branch with ``git checkout -b ``. + See `GitHub's documentation on branches `_ + for more information. + +* When you feel ready, open a pull request on GitHub. + **This does not have to be when you think you have finished the code!** + A PR runs tests and builds documentation. + This will allow others to review your code and + help you make sure it is correct. + It's always a good way to get feedback and validation, + as well as collaborate with other people. + See `GitHub's documentation on PRs `_ + for more information. diff --git a/docs/source/customising/documentation.rst b/docs/source/customising/documentation.rst new file mode 100644 index 0000000..5bc7877 --- /dev/null +++ b/docs/source/customising/documentation.rst @@ -0,0 +1,142 @@ +.. _add-docs: + +Documentation +============= +Documentation is important for your users and for yourself. + +The documentation is built using `Sphinx `_. + +Generally, a project will have a few types of documentation: + +* A ``README`` style overview, providing an quick introduction to the package + (or the subdirectory in which it is included) (a base-level ``README.md`` file + is :ref:`automatically generated by the cookiecutter `) + +* User guide-type documentation, which explains how and why to use the package. + While it may contain code examples, it's typically more of a broad + overview of package usage. + For example, this page is user-guide-like documentation. + A stub page for user-guide-like documentation is created in + ``docs/source/getting_started.rst``. + +* API documentation, which explains how to use the code. + This is often automatically generated from docstrings in the code. + A stub page for API documentation is created in + ``docs/source/api.rst``. + +The template ``docs/`` directory contains configuration files and initial stub pages for generating User Guide and API documentation using `Sphinx <(https://www.sphinx-doc.org>`_. + +.. _documentation-writing: + +Writing documentation for Sphinx +-------------------------------- +The cookiecutter creates three initial pages for your documentation, found in +``docs/source/``: + +* ``index.rst``: the 'home page', including a table of contents +* ``getting_started.rst``: a stub page for user-guide-like documentation +* ``api.rst``: a page for API documentation, using Sphinx's autosummary extension + to automatically generate documentation from your code's docstrings, assumed to + be `NumPy style docstrings `_ + +These files are written in +`ReStructuredText format `_. +Modify these as you see fit, and add any additional pages in this folder. See the +`Sphinx User Guide `_ for help. + +.. _documentation-configuration: + +Configuring the documentation with Sphinx +----------------------------------------- +The documentation is configured in the ``docs/source/conf.py`` file. +This file contains settings for the documentation, such as the +project name, version, and theme. You can also add extensions +to the documentation. +More information on configuring Sphinx can be found in the +`Sphinx documentation `_. + +By default, the documentation is built using the MDAnalysis sphinx theme using +the default template MDAKits logo and `favicon`_, and includes +several useful extensions, e.g. to allow building of API docs from NumPy style docstrings. + +You can customise your documentation by: + +* **Add additional extensions and configuration options** - see the + `Sphinx documentaiton `_. + +* **Changing the theme** by modifying the ``html_theme`` variable in + ``docs/source/conf.py``. You could also add custom style sheets in the + ``docs/source/_static/`` and/or template pages in ``docs/source/_templates/``; + see the respective ``README.md`` files in those folders for more information. + +* **Changing the logo**: You can also change the logo by either modifying the + ``html_logo`` variable or by replacing the ``_static/logo/mdakits-placeholder-logo.png`` + file. + (This path is relative to the ``docs/source`` directory; the full path, relative + to the repository root, is ``docs/source/_static/logo/mdakits-placeholder-logo.png``.) + + Similarly, you can change the favicon by replacing the ``html_favicon`` + variable or by replacing the ``_static/logo/mdakits-empty-favicon-template.svg`` file. + + You are welcome to either create an entirely custom logo and favicon or to use + the provided templates. An ``mdakits-empty-logo-template.svg`` and + ``mdakits-empty-favicon-template.svg`` are provided in the + ``docs/source/_static/logo`` directory as templates for editing -- feel free to + place your logo within the gears! + + +.. _documentation-building: + +Building the documentation with Sphinx +-------------------------------------- +Building documentation requires different dependencies to you main package; +an initial list of dependencies is provided in ``docs/requirements.yaml`` which +can be used to create a new virtual environment or +:ref:`be added to the current virtual environment `. +If you documentaiton requires additional/different dependencies, include them +here and in ``pyproject.toml``. + +The configuration file ``docs/Makefile`` and ``docs/make.bat`` are also provided +to allow you to build your documentation. + +The documentation can be build by running the following command in the ``docs/`` directory: + +.. code-block:: bash + + $ cd docs + $ make html + +This will build the documentation (as ``.html`` files) in a ``docs/_build/`` +directory; you can now view these files to see your built documention. + + +.. _documentation-hosting: + +Hosting documentation with ReadTheDocs +-------------------------------------- + +If you selected the to 'include ReadTheDocs' when using the cookiecutter +(the default option), you can now use it to automatically build and host your +documentation. + +`ReadTheDocs `_ is an external service. To link it +to your repository, first log +in to ReadTheDocs using your GitHub account. Click ``Import a Project`` on the +ReadTheDocs dashboard (your project should appear here once it has pushed to GitHub). +After importing you project, ReadTheDocs will build your documentation, +and it will now appear online with it's very own URL (likely at +``https://{repo_name}.readthedocs.io``)! + +We strongly recommend turning on building documentation for your +pull requests to check and preview your docs. To do so: + +#. Go to the Admin tab +#. Go to Advanced Settings +#. Tick the "Build pull requests for this project" checkbox +#. Scroll down and remember to click "Save"! + +A test build of the documentation will now be created and can be viewed for each PR. + +Further configuration can be done on from the ReadTheDocs dashboard or +in the ``readthedocs.yaml`` file - see the `ReadTheDocs documentation `_. + diff --git a/docs/source/customising/github.rst b/docs/source/customising/github.rst new file mode 100644 index 0000000..34ccf10 --- /dev/null +++ b/docs/source/customising/github.rst @@ -0,0 +1,33 @@ + +Adding the project to GitHub +============================ + +The generated ``{repo_name}`` directory should be an initialised git repository. +We now need to connect it to GitHub: + +#. `Create a new repository on GitHub `_ . + **Do not** initialize the repo with a README, license, or any other files. +#. Push the local repository to GitHub. + The `GitHub documentation `_ should provide instructions for doing so, but in short: + + * Add the remote named ``origin`` with :code:`git remote add origin ` + * Push the local repository to the remote repository with :code:`git push -u origin main` + * Verify files were pushed successfully by checking on GitHub + + +.. _github-features: + +**GitHub features** + +The ``.github/`` directory contains configuration files for useful features in +GitHub, including: + +* ``workflows/gh-ci.yaml`` for :ref:`running Continuous Integration ` + using `GitHub Actions `_. Other GitHub + actions, e.g. for deployments, can be added to the ``workflows/`` directory. +* ``.github/ISSUE_TEMPLATE/`` and ``.github/PULL_REQUEST_TEMPLATE.md`` provide + templates that will be presented by GitHub to community members when making + Issues and Pull Requests on your project's repository. They will help guide + users/contributors to include all the relevant information, simplifying the + process for both you and them. + diff --git a/docs/source/customising/packaging.rst b/docs/source/customising/packaging.rst new file mode 100644 index 0000000..917db59 --- /dev/null +++ b/docs/source/customising/packaging.rst @@ -0,0 +1,84 @@ +Packaging and Releases +====================== + +.. _packaging: + +Packaging +--------- +A ``pyproject.toml`` file has been created by the cookiecutter to allow your +code to be packaged and installed by users. This file has been automatically +set up with relevant meta information, dependencies (both core and optional +dependencies for tests and documentaiton), and settings for additional features +including versioningit for :ref:`versioning your code `. +You can edit this file to alter and of this information as appropriate. + +A ``MANIFEST.in`` file is also created to identify additional files included +when packaging your code (e.g., additional comminity information like the +Code of Conduct). + +Includion of ``pyproject.toml`` should mean your code is installable from GitHub. + +It is also a good idea to upload your package onto a package repository such +as `PyPI `_ or `conda-forge `_ to +make installation even easier for your users. + +The `PyPI documentation `_ +contains instructions for creating distributions for your package and how to add +these to PyPI. The initial steps - creation of relevant files - have been +handled for you by the cookiecutter. +Once created, distribution files can also be used to +`add your package to conda-forge `_. + +As you develop your package, you should package and release new versions of your +code to give users access to the new features. + + +.. _version: + +Versioning +---------- +Tagging is a good way to keep references to a specific version of your code +that won't change. This is especially useful when you want to a new a new code release. +The ``cookiecutter`` uses `versioningit`_ to automatically determine your +package's version based on git tags. + +By default, the initial version has been set to ``0.0.0``. +You can install versioningit_ to check the current versioningit output from commandline: + +.. code-block:: bash + + $ cd + $ versioningit . + 0.0.0 + +As you add commits, the versioning will automatically update with +the commit hashes: + +.. code-block:: bash + + $ versioningit . + 0.0.0+1.g58bcaff + +To tag a version, use the following command: + +.. code-block:: bash + + git tag -a 0.1.0 -m "Version 0.1.0" + +This will create a tag called ``0.1.0`` with the message +"Version 0.1.0". You can then push this tag to GitHub with ``git push origin --tags``. + +After creating a tag, you can check the versioning again: + +.. code-block:: bash + + $ versioningit . + 0.1.0 + +Once the new tag has been pushed to GitHub, you can +`make a new release `_ +from this tag. + +If using PyPI/Conda-forge, you should also upload the new releases here to these. + +.. _versioningit: https://versioningit.readthedocs.io/en/stable/index.html diff --git a/docs/source/customising/tests.rst b/docs/source/customising/tests.rst new file mode 100644 index 0000000..1a4f00b --- /dev/null +++ b/docs/source/customising/tests.rst @@ -0,0 +1,91 @@ +Testing and Continuous Integration +================================== + +.. _writing-tests: + +Writing tests with Pytest +------------------------- +A subpackage ``{package_name}/tests/`` is provided for you to add your tests. +The cookiecutter uses `pytest `_; read the +`pytest documentation `_ +for more information on writing tests with pytest. + +The generated ``tests/`` subpackage includes several template files and examples +to get you stated: + +* ``conftest.py``, which demonstrates creation of a + `fixture `_ using + the example MDAnalysis logo datafile +* ``test_{package_name}.py``: an initial test module, where you add the tests + themselves, with initial sample tests for checking your package can be imported + and a basic test using the MDAnalysis logo picture setup up in ``conftest.py`` +* ``utils.py``: a utility file for other code useful for your tests, containing a + class for creating a dummy MDAnalysis Universe. + +If you opted to include a template analysis class when using the cookiecutter, an +``analysis`` subpackge is also created, containing a +``test_{template_analysis_class}.py`` module with initial framework for checking +your analysis class with a dummy universe. + +.. _running-tests: + +Running tests with Pytest +------------------------- +Running pytest requires additional dependencies. +``devtools/conta-denvs/test_env.yaml`` specifies the initial dependencies, +allowing you to easily :ref:`add them to your virtual environment `. + +Tests can then be run locally using: + +Depending on your project, you may end up with additional dependentices for +your tests; add them in both ``test_env.yaml`` and ``pyproject.toml``. + + +.. _continuous-integration: + +Running Continuous Integration with GitHub Actions +-------------------------------------------------- + +Continuous Integration (CI) for your project has been set up via a +`GitHub actions `_ workflow in +``.github/workflows/gh-ci.yaml``. This CI should begin automatically once the +code is on GitHub, and will run when you push changes to the main branch, a Pull +Request is made, and on a once-weekly schedule. + +The provided CI workflow include checks for: + +* running Pytest on with various combinations of operating system (ubuntu, + macOS, windows), Python versions, and MDAnalysis version ('latest' and 'develop') +* hooks to generate test coverage reports with `CodeCov `_ + (further setup required, see :ref:`test-covereage`) +* a code formatting check using `Pylint `_ +* a test to see if a source distribution can be built + +CI results will appear in the ``Actions`` tab on GitHub or in the PR, as appropriate. + +.. _test-coverage: + +Test coverage with Codecov +-------------------------- + +The MDAKits cookiecutter uses CodeCov for test coverage reporting. +To make use of this feature, you will first need to sign up at +`Codecov `_ and follow the instructions to +`set up this repository `_ +by adding the GitHub App Integration (Steps 1 and 2). +Uploading of the coverage report (Step 4) is already provided by the +:ref:`cookiecutter generated CI `. + +You may need to trigger some tests (e.g. by pushing to the GitHub repository) +and wait a few hours before seeing coverage reports appearing on Codecov. +You can use these reports (also visible from the `Actions` tab on GitHub and +in your PRs) to discover which parts of your code +are not checked by your current tests. +**You should ideally aim for >90% code coverage to ensure that +your package actually does what you think it does!** + +The ``.codecov.yml`` file contains configuration for Codecov. +Edit that file to modify settings, such as files to ignore +and what to include in the coverage report. +See the `Codecov docs `_ for more information. + diff --git a/docs/source/files.rst b/docs/source/files.rst new file mode 100644 index 0000000..8e8c367 --- /dev/null +++ b/docs/source/files.rst @@ -0,0 +1,306 @@ +.. _files-label: + +Files Overview +=============== +The MDAKit cookiecutter generated a large number of files, which can be +daunting. However, many do no require editing or input from you, or are only +required to make use of optional features. + +The table below provides a summart of the generated files, (this links to the +relevant sections of documentation), and an indication of if the file is +"required" or likely to require modification. + +**Is this file 'required'?** + +There are several ways one could consider defining a 'required file'. The table below uses the +follow classifications: + +* **YES** - files that are central to your Python package being a Python package +* **REGISTRATION REQUIREMENT** - files that are not required for the package to work, but are required if you wish to register your MDAKit on the Registry +* **RECOMMENDED** - files that provide additional options not required for MDAKit registration, but that are still recommended for a good software package. Some of these are required in order for certain (optional) features to work; these are noted +* **OPTIONAL** - other files that may still be useful +* **NO** - files that are included only for illustative purposes or to guide you (the developer) + + +**Will I need to modify this file?** + +* **YES** - files that (if you keep) you'll have to change +* **PROJECT DEPENDENT** - files that will need to be modified in some, but not all cases +* **OPTIONAL** - files that you can opt to edit to e.g. replace default selections or add additional customisation +* **NO** - files where it's unlikely you'll need to change any options, or that you shouldn't touch at all (unless you know what you're doing) + + +.. list-table:: Cookiecutter files + :widths: 10 10 35 15 15 + :header-rows: 1 + + * - Name + - Category + - Description + - "Required?" + - Modify? + * - ``LICENSE`` + - :ref:`GENERAL INFORMATION ` + - File containing the details of the GPLv2 license, the default license for packages developed from the MDAKit cookiecutter + - **YES** - without a clear license, *no-one* can legally use your code + - **OPTIONAL** - you can opt for a license other than GPLv2 + * - ``README.md`` + - :ref:`GENERAL INFORMATION ` + - A basic introduction/overview of the package; this file will be rendered on the GitHub repo's home + - **REGISTRATION REQUIREMENT** - this is the minimum form of documentation your project should have + - **OPTIONAL** - ammend as you suits your project + * - ``CODE_OF_CONDUCT.md`` + - :ref:`COMMUNITY ` + - Rules for behaviour for all members of the project's community (users and developers). + - **RECOMMENDED** - setting clear rules and expectations is the foundation for a healthy community + - **OPTIONAL** - ammend as you suits your project + * - ``CONTRIBUTING.md`` + - :ref:`COMMUNITY ` + - Basic guide and instructions for those considering conbribution to the project + - **RECOMMENDED** - providing a guide to contributing will lower the entry barrier for first-time contributors to your project + - **OPTIONAL** - ammend as you suits your project + * - ``AUTHORS.md`` + - :ref:`DOCUMENTING CHANGES ` + - List of all contributors to the project + - **RECOMMENDED** - tracking all contributors to your project is important for giving credit + - **YES** - this file will be ammended whenever there is a new contributor + * - ``CHANGELOG.md`` + - :ref:`DOCUMENTING CHANGES ` + - Curated log of notable changes (and corresponding versions) made as the package is developed + - **RECOMMENDED** - keeping a changelog lets both developers and users know what major changes have been introduced and when + - **YES** - this file will be ammended whenever a notable change is made to the project + * - ``.gitignore`` + - :ref:`VERSION CONTROL` + - Stock helper file telling git what file name patters to ignore when adding files + - **RECOMMENDED** - this will reduce clutter in your commit history + - **NO** - this is a stock file that should cover all likely cases + * - ``.github/`` + - :ref:`GITHUB FEATURES ` + - *Files for options GitHub features* + - + - + * - ``.github/workflows/`` + - :ref:`GITHUB FEATURES ` + - *Workflow confugration files for running automated processes using GitHub actions* + - *RECOMMENDED - having at least a CI workflow to automate tests and checks is recommended* + - *OPTIONAL - you can opt to add additional GitHub Actions workflows here* + * - ``.github/ISSUE_TEMPLATE/`` + - :ref:`GITHUB FEATURES ` + - *Templates for GitHub Issues* + - *RECOMMENDED - template issues files will likely make things easier for both issue raisers and responders* + - *NO - the standard templates are already included, though you may also add custom templates* + * - ``.github/ISSUE_TEMPLATE/bug_report.md`` + - :ref:`GITHUB FEATURES ` + - Template that will be provided to contributors when making a "bug report" issue on GitHub + - **RECOMMENDED** - templates will likely make things easier for both you and the contributor + - **NO** - this is a standard template unlikely to need changing, though you can modify it if you wish + * - ``.github/ISSUE_TEMPLATE/feature_request.md`` + - :ref:`GITHUB FEATURES ` + - Template that will be provided to contributors when making a "feature request" issue on GitHub + - **RECOMMENDED** - templates will likely make things easier for both you and the contributor + - **NO** - this is a standard template unlikely to need changing, though you can modify it if you wish + * - ``.github/PULL_REQUEST_TEMPLATE.md`` + - :ref:`GITHUB FEATURES ` + - Template that will be provided to contributors when making a "Pull Requestion" on GitHub + - **RECOMMENDED** - templates will likely make things easier for both you and the contributor + - **NO** - this is a standard template unlikely to need changing, though you can modify it if you wish + * - ``{package_name}/`` + - :ref:`CODE ` + - *The import pacakge, containing your project's code* + - *YES - this is where your code itself will live* + - **YES** - you'll need to add your own code! + * - ``{package_name}/__init__.py`` + - :ref:`CODE ` + - __init__.py file to mark your code package + - **YES** - this allows ``{package_name}`` to be imported (and sets your code's version) + - **PROJECT DEPENDENT** - you may wish to add + * - ``{package_name}/analysis/`` + - :ref:`CODE ` + - *(Optional, only created if ' template analysis class' is selected) Directory for analysis code; set up with an (empty) __init__ .py* + - *NO - you do not have to follow the initial generated subpackage structure* + - *YES - if you opt to keep this cookiecutter-generated subpackage, you'll need to add your own code here!* + * - ``{package_name}/analysis/{class_name}.py`` + - :ref:`CODE ` + - (Optional, only created if ' template analysis class' is selected) File containing a template analysis class, based off MDAnalysis; ``AnalysisBase``. + - **RECOMMENDED** - if your code features a frame-by-brame timeseries analysis, it is highly recommended to start with a Class based on ``AnalysisBase``. + - **YES** - if using this template, you'll need to add your own code here! + * - ``{package_name}/data/`` + - :ref:`CODE ` + - *Subpackage for including additional (non-code) date to be included in the package; set up with an empty ``__init__.py`` file* + - *NO - this subpackage demonstrates how additional non-code files can be included, but is not required* + - *OPTIONAL - if you do wish to include non-code data, you'll add them here* + * - ``{package_name}/data/README.md`` + - :ref:`CODE ` + - Additional information for including non-code files with your package + - **NO** - but you may wish to refer to this file in future, so keep it around + - **NO** - the purpose of this file is only to provide information to you, the devloper + * - ``{package_name}/data/files.py`` + - :ref:`CODE ` + - Module for setting up non-code files to be imported elsewhere in the package + - **OPTIONAL** - a central file to set up importing of your non-coding will likely make things easier + - **YES** - if you opt to include non-code datafiles this way, you'll need to add them here + * - ``{package_name}/data/mda.txt`` + - :ref:`CODE ` + - An example data file (ASCII art of the MDAnalysis logo) to demonstrate inclusion of non-code data + - **NO** - this file is only for illustrative purposes + - **NO** - this file is only for illustrative purposes + * - ``devtools/`` + - *Misc.* + - + - + - + * - ``devtools/conda-envs/`` + - *Misc.* + - + - + - + * - ``{package_name}/tests/`` + - :ref:`TESTING ` + - *Directory for unit tests. Set up with an empty ``__init__.py``* + - *REGISTRATION REQUIREMENT - your MDAKit must have at least basic tests to be Registered!* + - *YES - you'll need to add your own tests!* + * - ``{package_name}/tests/conftest.py`` + - :ref:`TESTING ` + - File to set up pytest fixtures for use in your tests, containing an example fixture + - **OPTIONAL** - The example fixture can be removed, but fixtures are a very useful feature of pytest; if you have multiple fixtures/used in multiple places, keeping them in a separate file will help keep your tests organised + - **PROJECT DEPENDENT** - The example fixture can be removed, but whether you have fixtures to include here depend on your projects + * - ``{package_name}/tests/test_{package_name}.py`` + - :ref:`TESTING ` + - Initial test module for your package with pytest, containing sample tests + - **REGISTRATION REQUIREMENT** - to be registered, your MDAKit needs at least basic unit tests, which will live here (though note you can rename or rearrange this file) + - **YES** - add your tests here! The initial sample tests can be removed + * - ``{package_name}/tests/utils.py`` + - :ref:`TESTING ` + - Utility file for setting up other code useful for your tests, containing an example class for setting up a dummy Universe + - **OPTIONAL** - A separate file for setting up common utilities can help keep your tests more organised + - **PROJECT DEPENDENT** - The example fixture can be removed, but whether you have fixtures to include here depend on your projects + * - ``{package_name}/tests/analysis/`` + - :ref:`TESTING ` + - (Optional, only created if ' template analysis class' is selected) Subpackage for test on the package's analysis class; set up with empty ``__init__.py``. + - *NO - you do not have to follow the initial generated subpackage structure* + - *YES - if you opt to keep this cookiecutter-generated subpackage, you'll need to add your tests code here!* + * - ``{package_name}/tests/analysis/test_{analysis_class}.py`` + - :ref:`TESTING ` + - (Optional, only created if ' template analysis class' is selected) Example module with initial framework for tests on the package's analysis class using pytest + - **RECOMMENDED** - if your code features a frame-by-frame anaysis based on AnalysisBase, this file is a good place to start for writing your tests + - *YES - if you opt to keep this cookiecutter-generated subpackage, you'll need to add your tests code here!* + * - ``devtools/conda-envs/test_env.yaml`` + - :ref:`TESTING ` + - A configuration file for creating an environment with the required dependencies for running the project's tests using pytest + - **YES** - this will allow you to set up an environemnt with the tools needed to run your tests locally + - **PROJECT DEPENDENT** - you may need to modify this file if your tests have additional dependencies + * - ``.github/workflows/gh-ci.yaml`` + - :ref:`CONTINUOUS INTEGRATION ` + - A configuration file specifying steps for running Continuous Integration, using `GitHub Actions `_ + - **RECOMMENDED (required for CI)** - many checks can be run manually, but having them run automatically through CI will make your (and other contributors') lives easier + - **OPTIONAL** - if you know what you're doing, you can add additional CI checks and change settings in this file + * - ``.codecov.yml`` + - :ref:`TESTING (code coverage) ` + - Settings for `Codecov `_, a test coverage reporting tool + - **OPTIONAL** - this file provides additional options for configuration, but is not required for running codecov + - **OPTIONAL** - adjust this file to suit your preferences + * - ``docs/`` + - :ref:`DOCUMENTATION ` + - *Configuration files and template source files for building a User Guide using Sphinx* + - *RECOMMENDED - a README.md provides a minimal level of documentation, but a User Guide offering more details is highly recommended* + - *YES - if you opt to create a User Guide using Sphinx, you can add your documentation information here* + * - ``docs/source/`` + - :ref:`DOCUMENTATION ` + - *Source files for building documentation using Sphinx* + - *RECOMMENDED (required for building documentation with Sphinx)* + - *YES - if you opt to build your User Guide using Sphinx, you'll add your documentation here* + * - ``docs/source/index.rst`` + - :ref:`DOCUMENTATION ` + - Home page for your project's User Guide, generated using Sphinx + - **RECOMMENDED (required for building documentaiton using Sphinx)** - if you build a User Guide using Sphinx, you'll need at least this home page + - **YES** - add details here as appropriate for your project + * - ``docs/source/getting_started.rst`` + - :ref:`DOCUMENTATION ` + - Stub page for User Guide-style documentation on your project's User Guide, generated using Sphinx + - **RECOMMENDED** - providing users with details on how to get started using your package is highly recommended + - **OPTIONAL** - but you need not follow the autogenerated file structure + * - ``docs/source/api.rst`` + - :ref:`DOCUMENTATION ` + - Stub page for API-stype documentation on your project's User Guide, generated using Sphinx + - **RECOMMENDED** - providing users with an API guide is highly recommended + - **OPTIONAL** - including API-style docs is recommended, but you need + * - ``docs/source/conf.py`` + - :ref:`DOCUMENTATION ` + - Configuration file for building documentation using Sphinx + - **RECOMMENDED (required if using Sphinx)** + - **OPTIONAL** - you can alter this file to customise your documentation + * - ``docs/source/_static/`` + - :ref:`DOCUMENTATION ` + - Static files for customising your documentation, such as logos and style sheets; see the encloded ``REAMDE`` for more information. + - *OPTIONAL* + - *OPTIONAL - you can add files here to customise your documentation* + * - ``docs/source/_templates/`` + - :ref:`DOCUMENTATION ` + - Template files for customising your documentation; see the encloded ``REAMDE`` for more information. + - *OPTIONAL* + - *OPTIONAL - you can add files here to customise your documentation* + * - ``docs/source/_static/logos/`` + - :ref:`DOCUMENTATION ` + - Placeholer and template logo files for MDAKits + - *OPTIONAL* + - *OPTIONAL - you can add files here to customise your documentation* + * - ``docs/source/_static/logos/mdakits-empty-favicon-template.svg`` + - :ref:`DOCUMENTATION ` + - Placeholder favicon for the User Guide documentaiton + - *OPTIONAL* + - *OPTIONAL - you can alter this file to customise your documentation* + * - ``docs/source/_static/logos/mdakits-empty-logo-template.svg`` + - :ref:`DOCUMENTATION ` + - Template "empty gears" MDAKits logo file, which you can edit to make your own logo + - **NO** - this file is here to provide you with a template to edit, if you wish + - *OPTIONAL - you can alter this file to customise your documentation* + * - ``docs/source/_static/logos/mdakits-placeholder-logo.png`` + - :ref:`DOCUMENTATION ` + - Placeholder logo for the User Guide documentation + - *OPTIONAL* + - *OPTIONAL - you can alter this file to customise your documentation* + * - ``docs/README.md`` + - :ref:`DOCUMENTATION ` + - Reference file containing instructions for building the documentaiton + - **NO** - this file is for your reference (but you might want to view it later, so keep it around) + - **NO** - this file serves only as a reference for developers + * - ``docs/requirements.yaml`` + - :ref:`DOCUMENTATION ` + - Configuration file listing the depencencies for building the documentation + - **OPTIONAL (required if you want to build documentaiton locally/with ReadTheDocs)** + - **PROJECT DEPENDENT** - if your documentation has additional dependencies, you'll need to add them here + * - ``docs/Makefile`` + - :ref:`DOCUMENTATION ` + - Confiugration file for building documentation using Sphinx + - **OPTIONAL (required if you want to build documentaiton locally/with ReadTheDocs)** + - **NO** - you shouldn't need to touch this file + * - ``docs/make.bat`` + - :ref:`DOCUMENTATION ` + - Script file for building documentation using Sphinx + - **OPTIONAL (required if you want to build documentaiton locally/with ReadTheDocs)** + - **NO** - you shouldn't need to touch this file + * - ``readthedocs.yaml`` + - :ref:`DOCUMENTATION ` + - Settings for `ReadTheDocs `_, a tool for building and hosting documentation + - **OPTIONAL (required if you want to use ReadTheDocs)** + - **NO** - not likely, unless you know what you're doing + * - ``pyproject.toml`` + - :ref:`PACKAGING ` + - Configuration file for the Python package + - **YES** - this is the main configuration file for your package and required for users to be able to isntall your code + - **PROJECT DEPENDENT** - + * - ``MANIFEST.in`` + - :ref:`PACKAGING ` + - List of additional files to include (or exclude) when packaging code for distrubution + - **NO** - most key files will be included by default + - **NO** - + * - ``.pre-commit-config.yaml`` + - CODE (style checking) + - Settings for pre-commit hooks to run formatting and linting checks on your code + - **OPTIONAL** - pre-commit hooks can be useful for finding stylistic errors in your code before making commits, but are not required + - **OPTIONAL** - you can change settings in this file as descired + * - ``.pylintrc`` + - CODE (style checing) + - Settings for `PyLint `_ + - **OPTIONAL (required to run PyLint)** + - **OPTIONAL** - you can change settings in this file as descired diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 0000000..e4a9fdd --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,225 @@ +Getting Started +############### + +The page demonstrates the basic usage of the MDAKit cookiecutter to generate a +skeleton for a Python package. +Once created, you will then need to add code to and customise your package; +this is covered in the next section. + +Requirements +============ + +You will need the following: + * Python 3.9+ + * The `cookiecutter`_ tool installed + * A GitHub account + + +Basic Usage +=========== + +To run the cookiecutter, run the followign command: + +.. code:: + + $ cookiecutter gh:MDAnalysis/cookiecutter-mdakit + +You will be prompted to answer a series of questions to begin the initial +customisation of your project. These prompts, and some example answers are +illustrated here: + +.. literalinclude:: generated/cookiecutter_cli.log + :language: bash + + +The :ref:`options-label` section below provides more details on these options, +default values (if applicable), what they mean, and what they affect. + +Running the cookiecutter will the above responses will generate the following +output skeleton, (as well as initialise a git repository `example-repository`, +make an initial commit, and add a "0.0.0" tag to set the initial version): + +.. literalinclude:: generated/cookie_tree.txt + + +This may seem quite daunting at first glance, but not every file is strictly +necessary/one that you need to worry about. The following sections on +:ref:`customising-label` will address relevant files as the come up. See also +:ref:`files-label` for an overview of these files. + + +.. _options-label: + +Options +======= + +This section goes into the options you can choose in the cookiecutter, +what they mean, and what they affect. +If there are default values, they are explained. + +project_name +------------ + +This is the name of the project you would +use when writing about it in the documentation. +This can be anything, e.g. have spaces and hyphens. + +repo_name +--------- + +This is the name of the directory containing +the package. It cannot contain spaces. +This value is used to generate the URL +to the project on GitHub +(i.e. ``github.com//``). + +**Default value:** the ``project_name`` in lowercase, +with spaces and hyphens replaced with underscores. + +package_name +------------ + +This is the name of the module you would use +when importing your package. It must +follow Python module naming rules, i.e. it cannot +have spaces or hyphens. + +**Default value:** the ``repo_name`` in lowercase, +with spaces and hyphens replaced with underscores. + +description +----------- + +Give a short description of the project to appear in the README. + +github_username +--------------- + +This should be your *personal* GitHub username. +It is used for giving you credit in AUTHORS.md. +github_host_account +------------------- + +This should be the GitHub account name used to host the +repository. In most cases, this will be the same as +the GitHub username; however, if you are creating a +package for an organisation, use the organisation +account name. This value is used to generate the URL +to the project on GitHub +(i.e. ``github.com//``). + +If you set this to ``MDAnalysis``, +we will set some options for you. +For example, the default logo and favicon +will be the MDAnalysis logo and favicon. +You will also have a footer detailing our +privacy policy. + +If you set this to another value, +there will be entries in the documentation +`conf.py` that use a placeholder logo and favicon. + +Please see our `mdanalysis-sphinx-theme`_ +documentation for more information. + +**Default value:** the ``github_username``. + +.. _`mdanalysis-sphinx-theme`: https://mdanalysis-sphinx-theme.readthedocs.io/en/latest/ + +author_name +----------- + +This should be the name you prefer to go by, not your username. +It is used for giving you credit in files such as +``AUTHORS.md``, ``setup.py``, and other packaging materials. + +author_email +------------ + +This should be an email address that you are comfortable +getting contacted at. It is used for contact details +in files such as ``AUTHORS.md``, ``setup.py``, and other packaging materials. +It is also used as the point of contact in ``CODE_OF_CONDUCT.md``. + +dependency_source +----------------- + +This option determines which sources to use for dependencies for the package. +It affects the continuous integration testing, as well as +the dependency files written. The three choices +(``conda-forge``, ``anaconda``, and ``pip``) +are explained below. + +**Default value:** ``conda-forge``. + + +conda-forge +~~~~~~~~~~~ + +This option looks for dependencies first in the ``conda-forge`` channel, +then the default ``anaconda`` channel, before falling back to ``pip``. + +.. note:: + + We **highly recommend** using ``conda-forge``. + ``conda`` is a great package manager for creating + isolated environments, and managing dependencies between them. + Moreover, many packages are available on ``conda-forge`` + that are not on the default ``anaconda`` channel or ``pip``. + + + +anaconda +~~~~~~~~ + +This option still uses ``conda`` to manage dependencies, +but only uses the ``anaconda`` channel and ``pip`` fallback. +This option would install MDAnalysis from `PyPI`_ . +as it is not available on the default ``anaconda`` channel. + +pip +~~~ + +This option only installs packages from `PyPI`_. + + +include_ReadTheDocs +------------------- + +This option determines whether to include +ReadTheDocs configuration (``readthedocs.yaml``) +in the package. It does not affect the documentation itself. +We recommend keeping ReadTheDocs, as it is a standard and easy way +to automatically build documentation online. + +**Default value:** "y" (True) + + +template_analysis_class +----------------------- + +This option triggers the building of a skeleton custom +analysis class, and associated tests. +If a class name is given, it is used as the name of the +analysis class. If it is not given, this step is skipped. + +We strongly encourage using this option if you are planning +to write custom analysis, as it copies a helpful +template with comments and notes to modify. + +**Default value:** skip + + +.. _PyPI: https://pypi.org/ + + + + + + + + + + + +.. _cookiecutter: https://cookiecutter.readthedocs.io/en/stable/ diff --git a/docs/source/index.rst b/docs/source/index.rst index 062121a..60f74a1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,11 +27,11 @@ Starting repositories can be created from this template so you can focus on what .. toctree:: :maxdepth: 1 - :caption: General - :hidden: + :caption: Usage - usage - options + getting_started + customising + files .. toctree:: :maxdepth: 1 diff --git a/docs/source/options.rst b/docs/source/options.rst index 157d4ba..e69de29 100644 --- a/docs/source/options.rst +++ b/docs/source/options.rst @@ -1,164 +0,0 @@ -.. _options-label: - -Options -======= - -This page goes into the options you can choose in the cookiecutter, -what they mean, and what they affect. -If there are default values, they are explained. - -project_name ------------- - -This is the name of the project you would -use when writing about it in the documentation. -This can be anything, e.g. have spaces and hyphens. - -repo_name ---------- - -This is the name of the directory containing -the package. It cannot contain spaces. -This value is used to generate the URL -to the project on GitHub -(i.e. ``github.com//``). - -**Default value:** the ``project_name`` in lowercase, -with spaces and hyphens replaced with underscores. - -package_name ------------- - -This is the name of the module you would use -when importing your package. It must -follow Python module naming rules, i.e. it cannot -have spaces or hyphens. - -**Default value:** the ``repo_name`` in lowercase, -with spaces and hyphens replaced with underscores. - -description ------------ - -Give a short description of the project to appear in the README. - -github_username ---------------- - -This should be your *personal* GitHub username. -It is used for giving you credit in AUTHORS.md. - -github_host_account -------------------- - -This should be the GitHub account name used to host the -repository. In most cases, this will be the same as -the GitHub username; however, if you are creating a -package for an organisation, use the organisation -account name. This value is used to generate the URL -to the project on GitHub -(i.e. ``github.com//``). - -If you set this to ``MDAnalysis``, -we will set some options for you. -For example, the default logo and favicon -will be the MDAnalysis logo and favicon. -You will also have a footer detailing our -privacy policy. - -If you set this to another value, -there will be entries in the documentation -`conf.py` that use a placeholder logo and favicon. - -Please see our `mdanalysis-sphinx-theme`_ -documentation for more information. - -**Default value:** the ``github_username``. - -.. _`mdanalysis-sphinx-theme`: https://mdanalysis-sphinx-theme.readthedocs.io/en/latest/ - -author_name ------------ - -This should be the name you prefer to go by, not your username. -It is used for giving you credit in files such as -``AUTHORS.md``, ``setup.py``, and other packaging materials. - -author_email ------------- - -This should be an email address that you are comfortable -getting contacted at. It is used for contact details -in files such as ``AUTHORS.md``, ``setup.py``, and other packaging materials. -It is also used as the point of contact in ``CODE_OF_CONDUCT.md``. - -dependency_source ------------------ - -This option determines which sources to use for dependencies for the package. -It affects the continuous integration testing, as well as -the dependency files written. The three choices -(``conda-forge``, ``anaconda``, and ``pip``) -are explained below. - -**Default value:** ``conda-forge``. - - -conda-forge -~~~~~~~~~~~ - -This option looks for dependencies first in the ``conda-forge`` channel, -then the default ``anaconda`` channel, before falling back to ``pip``. - -.. note:: - - We **highly recommend** using ``conda-forge``. - ``conda`` is a great package manager for creating - isolated environments, and managing dependencies between them. - Moreover, many packages are available on ``conda-forge`` - that are not on the default ``anaconda`` channel or ``pip``. - - - -anaconda -~~~~~~~~ - -This option still uses ``conda`` to manage dependencies, -but only uses the ``anaconda`` channel and ``pip`` fallback. -This option would install MDAnalysis from `PyPI`_ . -as it is not available on the default ``anaconda`` channel. - -pip -~~~ - -This option only installs packages from `PyPI`_. - - -include_ReadTheDocs -------------------- - -This option determines whether to include -ReadTheDocs configuration (``readthedocs.yaml``) -in the package. It does not affect the documentation itself. -We recommend keeping ReadTheDocs, as it is a standard and easy way -to automatically build documentation online. - -**Default value:** "y" (True) - - -template_analysis_class ------------------------ - -This option triggers the building of a skeleton custom -analysis class, and associated tests. -If a class name is given, it is used as the name of the -analysis class. If it is not given, this step is skipped. - -We strongly encourage using this option if you are planning -to write custom analysis, as it copies a helpful -template with comments and notes to modify. - -**Default value:** skip - - -.. _PyPI: https://pypi.org/