From 64ad7a289c7ca09cc03c343854c072a98d85017f Mon Sep 17 00:00:00 2001 From: Jeff Jennings Date: Wed, 26 Jun 2024 00:39:38 -0400 Subject: [PATCH] README: move repo layout info to docs --- README.md | 19 ------------------- docs/getting_started.rst | 29 +++++++++++++++++++++++++++-- docs/index.rst | 4 ++-- 3 files changed, 29 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6cab832..b73e6e5 100644 --- a/README.md +++ b/README.md @@ -8,22 +8,3 @@ Template Python repository This is a basic template for a Python repository, with the components needed to develop and release an open source software package. These include unit tests; type annotations; a documentation site with an API; and continuous integration for tests, code coverage, linting/formatting, type checking, and publishing the docs. See the [docs](https://cca-software-group.github.io/py_template/) for a 'Getting Started' guide with steps on how to make your own Python repo using this template and what to do next to build your own package. - -The file structure of this repo is: -1) `.github` has two subfolders: - * `ISSUE_TEMPLATE` has files that are templates users can select from when opening an issue in the repo on GitHub - * `workflows` implements continuous integration (CI) through GitHub 'actions' that are automatically run according to a chosen trigger. These are currently: - - `docs.yml` builds and deploys the [documentation site](https://cca-software-group.github.io/py_template/index.html) when a push is made to `main`. - - `format_lint.yml` lints and formats the code on each push using `ruff` and `black`. - - `tests.yml` runs tests with `pytest` on each push. - - `type_check.yml` runs type checking with `mypy` on each push. The CI continues even if the type checker finds errors. -2) `docs` has the files used to build the documentation site with `Sphinx`, with the site content in `index.rst` and `py_API.rst`. -3) `py_template` is the source code folder, with the necessary `__init__.py` and example code file, `example_module.py`. -4) `test` has the unit tests, with example tests for the source code file in `test_example_module.py`. When you add new test files, they should start with `test_` so `pytest` recognizes them. -5) `.gitignore` is a list of file types that are ignored when you push to the remote repo. -6) `HISTORY.rst` is the change log that you should update as you implement the packaged version. -7) `LICENSE.rst` has the package's license. -8) `MANIFEST.in` has instructions for how to pre-process the package (which files to exclude) when preparing to release it to PyPI (the Python Package Index). Packages uploaded to PyPI can be installed by users with `pip`. -9) `README.md` is the file you're reading! It has badges that use the CI to display if the unit tests are passing, what percentage of the code is covered by the tests, and if the docs build and deploy is passing. -10) `pyproject.toml` is the configuration file for the entire package. See the [Python docs](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for a description of its contents. -11) `tox.ini` is a configuration file used to set up testing. See the [tox docs](https://tox.wiki/en/latest/index.html) for a description of its contents. diff --git a/docs/getting_started.rst b/docs/getting_started.rst index a038575..d8ed6f8 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -1,11 +1,35 @@ Getting started =============== -| To make a new Python repo using `py_template`: +Repo file structure +------------------- +| The `py_template` repo has a common file structure: +| 1) `.github` has two subfolders: +| * `ISSUE_TEMPLATE` has files that are templates users can select from when opening an issue in the repo on GitHub +| * `workflows` implements continuous integration (CI) through GitHub 'actions' that are automatically run according to a chosen trigger. These are currently: +| - `docs.yml` builds and deploys this docs site when a push is made to `main`. +| - `format_lint.yml` lints and formats the code on each push using *ruff* and *black*. +| - `tests.yml` runs tests with *pytest* on each push. +| - `type_check.yml` runs type checking with *mypy* on each push. The CI continues even if the type checker finds errors. +| 2) `docs` has the files used to build the docs with *Sphinx*, with the site content in `index.rst` and `py_API.rst`. +| 3) `py_template` is the source code folder, with the necessary `__init__.py` and example code file, `example_module.py`. +| 4) `test` has the unit tests, with example tests for the source code file in `test_example_module.py`. When you add new test files, they should start with `test_` so *pytest* recognizes them. +| 5) `.gitignore` is a list of file types that are ignored when you push to the remote repo. +| 6) `HISTORY.rst` is the change log that you should update as you implement the packaged version. +| 7) `LICENSE.rst` has the package's license. +| 8) `MANIFEST.in` has instructions for how to pre-process the package (which files to exclude) when preparing to release it to PyPI (the Python Package Index). Packages uploaded to PyPI can be installed by users with *pip*. +| 9) `README.md` is the file you're reading! It has badges that use the CI to display if the unit tests are passing, what percentage of the code is covered by the tests, and if the docs build and deploy is passing. +| 10) `pyproject.toml` is the configuration file for the entire package. See the `Python docs `_ for a description of its contents. +| 11) `tox.ini` is a configuration file used to set up testing. See the `tox docs `_ for a description of its contents. + +Making a new Python repo using `py_template` +-------------------------------------------- | 1) Click the 'Use this template' button at the top-right of the GitHub page. | 2) In your new repo, rename (search and replace) all instances of "py_template" with the name for your package. | 3) Update the `authors` field in `pyproject.toml`, `docs/conf.py` and `LICENSE.rst` (the template is partially based on the `OpenAstronomy packaging guide `_, so please retain that aspect of the license). +Interacting with your new code +------------------------------ | After cloning your repo to your computer, from the project's root directory, you can: | 1) Install your package with all optional dependencies: | `pip install -e ".[dev]"` @@ -20,7 +44,8 @@ Getting started | After building the docs, view them with | `open docs/_build/html/index.html` -| When you're writing your software, you may want to: +Developing your package +----------------------- | 1) Add new unit tests in `test/test_*.py` for new functions and classes. Test not just whether the new code runs, but also if it gives a sensible result. | 2) Update the docs, including the main page (`docs/index.rst`), adding pages, and updating the API (`docs/py_API.rst`) when you add new functions and classes. | 3) Optionally change the CI triggers for each of the actions in `.github/workflows`. diff --git a/docs/index.rst b/docs/index.rst index 9973709..7981068 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,12 +3,12 @@ Documentation Welcome to the `py_template` docs! -See the 'Getting started' guide for steps on how to make your own Python repo using this template and considerations for building your own package. +See the 'getting started' guide for steps on how to make your own Python repo using this template and considerations for building your own package. The API has example entries for the function and class in `example_module.py`. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Tutorials Getting started guide