From a0bd4bbe8302a3981cf39b2c1c24462d07cca923 Mon Sep 17 00:00:00 2001 From: Jeff Jennings Date: Wed, 26 Jun 2024 00:19:53 -0400 Subject: [PATCH] docs: add getting started guide --- docs/conf.py | 2 +- docs/getting_started.rst | 27 +++++++++++++++++++++++++++ docs/index.rst | 14 +++++++++++--- 3 files changed, 39 insertions(+), 4 deletions(-) create mode 100644 docs/getting_started.rst diff --git a/docs/conf.py b/docs/conf.py index bde1f94..6978a79 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,7 +14,7 @@ release = __version__ project = "py_template" -author = "CCA Software Group" +author = "Jeff Jennings" copyright = f"{datetime.datetime.now().year}, {author}" # noqa: A001 # -- General configuration --------------------------------------------------- diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..a038575 --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,27 @@ +Getting started +=============== + +| To make 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). + +| 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]"` +| 2) Run your tests: +| `pytest .` +| 3) Run linting and formatting to see their effects: +| `black .` and `ruff check .` +| 4) Run type checking using mypy: +| `mypy --strict .` +| 5) Build your docs locally: +| `tox -e build_docs` or `cd docs; make html`. +| After building the docs, view them with +| `open docs/_build/html/index.html` + +| When you're writing your software, you may want to: +| 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`. +| 4) Update the changelog in `HISTORY.rst` when you're ready to release your first version of the code! \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 70c373f..9973709 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,11 +3,19 @@ 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. + The API has example entries for the function and class in `example_module.py`. -.. toctree:: +.. toctree:: + :maxdepth: 2 + :caption: Tutorials + + Getting started guide + +.. toctree:: :maxdepth: 1 :caption: Reference - API - Index \ No newline at end of file + API + Index \ No newline at end of file