Merge pull request #1 from rs-station/setup

Create basic package

.github/workflows/build_docs.yml

@@ -0,0 +1,52 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    # Skip docs if 'skip docs' is contained in latest commit message
+    if: "!contains(github.event.head_commit.message, 'skip docs')"
+
+    steps:
+
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.9
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[docs]"
+    - name: Set up Pandoc
+      uses: r-lib/actions/setup-pandoc@v2
+
+    - name: Build documentation
+      run: |
+        cd docs
+        make clean
+        make html
+    - name: Commit documentation changes to gh-pages
+      run: |
+        cd docs
+        git clone https://github.com/rs-station/rs-template.git --branch gh-pages --single-branch gh-pages
+        cd gh-pages
+        cp -r ../_build/html/* .
+        git config --local user.email "action@github.com"
+        git config --local user.name "GitHub Action"
+        git add .
+        git diff --quiet && git diff --staged --quiet || git commit -m "Upload documentation from latest commit"
+    - name: Push changes to gh-pages
+      uses: ad-m/github-push-action@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: "gh-pages"
+        directory: "docs/gh-pages"

.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  pull_request: {}
+  workflow_dispatch:
+
+jobs:
+
+  test:
+    name: ${{ matrix.platform }} (${{ matrix.python-version }})
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10']
+        platform: [ubuntu-latest]
+
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.12.1
+        with:
+          access_token: ${{ github.token }}
+
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e .[test]
+
+      - name: Test
+        run: pytest --color=yes --cov --cov-report=xml --cov-report=term-missing
+
+      - name: Coverage
+        uses: codecov/codecov-action@v4
+
+  deploy:
+    name: Deploy
+    needs: test
+    if: "success() && startsWith(github.ref, 'refs/tags/')"
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: install
+        run: |
+          git tag
+          pip install -U pip
+          pip install -U build twine
+          python -m build
+          twine check dist/*
+          ls -lh dist
+
+      - name: Build and publish
+        run: twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_KEY }}
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

.github/workflows/cron.yml

@@ -0,0 +1,51 @@
+name: --pre Test
+# An "early warning" cron job that will install dependencies
+# with `pip install --pre` periodically to test for breakage
+# (and open an issue if a test fails)
+
+on:
+#  schedule:
+#    - cron: "0 16 * * 1" # monday at noon est
+  workflow_dispatch:
+
+jobs:
+
+  test:
+    name: ${{ matrix.platform }} (${{ matrix.python-version }})
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10']
+        platform: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install tox tox-gh-actions
+
+      - name: Test with tox
+        run: python -m tox
+        env:
+          PLATFORM: ${{ matrix.platform }}
+      # If something goes wrong, we can open an issue in the repo
+      - name: Report Failures
+        if: ${{ failure() }}
+        uses: JasonEtco/create-an-issue@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PLATFORM: ${{ matrix.platform }}
+          PYTHON: ${{ matrix.python }}
+          RUN_ID: ${{ github.run_id }}
+          TITLE: '[test-bot] pip install --pre is failing'
+        with:
+          filename: .github/TEST_FAIL_TEMPLATE.md
+          update_existing: true

.github/workflows/test_docs.yml

@@ -0,0 +1,35 @@
+name: Test Documentation
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    # Skip docs if 'skip docs' is contained in latest commit message
+    if: "!contains(github.event.head_commit.message, 'skip docs')"
+
+    steps:
+
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.9
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[docs]"
+    - name: Set up Pandoc
+      uses: r-lib/actions/setup-pandoc@v2
+
+    - name: Build documentation
+      run: |
+        cd docs
+        make clean
+        make html

README.md

@@ -1,2 +1,85 @@
 # rs-template
-Template repo demonstrating best practices
+Template repo demonstrating best practices. Read through this file (and explore this repo) and make sure that your package includes all of the following. In some cases, you may opt for a reasonable alternative, but all of this core functionality should be present.
+
+## General organization
+
+The following files in this repo should be adapated for your repo:
+
+### [`pyproject.toml`](/pyproject.toml) configuration file
+This is the configuration file for the package. The example in this repo is a good starting point. Some things to note:
+ - I recommend copying the `[build-system]` and `[tool.hatch.version]` blocks exactly, and including `dynamic = ["version"]` in the `[project]` block. This allows you to version your package through numbered "releases" on GitHub. There are other ways to do this, but I think this is the best one.
+ - There are three different types of dependencies in this file. First, the core `dependencies = ` in the `[project]` block are python packages which are required for your package to function. The `[project.optional-dependencies]` block adds two more types of dependencies:
+     - `test`: Any packages necessary to run the test suite.
+     - `docs`: Any packages necessary to build the package documentation locally. More on this below.
+
+### [`setup.py`](/setup.py) legacy file
+Using `setup.py` to define package configuration and installation is deprecated. However, for legacy reasons, the `setup.py` file must exist. You can adapt the example in this repo.
+
+### [`LICENSE`](/LICENSE)
+Pick an open-source license to use, or copy the one here (MIT license).
+
+### [`tox.ini`](/tox.ini)
+Copy and adapt this file. This file defines configurations for GitHub actions that will be run.
+
+### [`.gitignore`](/.gitignore)
+Cookie-cutter python gitignore file.
+
+## Code
+The actual code for your package lives in the `/src/{package-name}` directory. This folder **must** contain an `__init__.py` file, even it is empty. Ideally, use the `__init__.py` file to define what can be imported from your package.
+
+### Code for command-line utilities
+Command-line utilities should be structured such that the utility can be called by calling some function, likely the `main` function. Then, you can add the following to your `pyproject.toml` to give this utility a name and make it available from the command line:
+
+```toml
+[project.scripts]
+"rs.template" = "rs_template._command_line:main"
+```
+
+## Docs
+The `/docs` folder contains the necessary files to build package documentation. The files `make.bat` and `Makefile` are entirely cookie-cutter and can be copied exactly.
+
+### `conf.py` configuration file for docs
+There are lots of fun options here, but I recommend the sensible defaults in the example file. 
+
+Note that if your documentation is to include a python API reference, you must include `"sphinx.ext.autodoc"` in `extensions = `. If your documentation is to include a command-line API reference, you must include `"sphinxcontrib.autoprogram"`.
+
+If you want your documentation to include rendered jupyter notebooks, you can find code for this in various commented-out options in this file.
+
+Note that the [`"myst_parser"`](https://myst-parser.readthedocs.io/en/latest/) extension allows pages to be written in a blend of markdown and reStructuredText. There are examples of this throughout the documentation.
+
+### `index.md`: Your homepage
+All websites need a homepage! This file can be written in markdown, and will be rendered into HTML based on the theme that you've picked. The only essential non-markdown element is the table of contents; see the `/docs/index.md` file in this repo for an example of the syntax.
+
+### Building docs locally
+Building docs locally is easy!
+
+ 1. Install your package, including the `[docs]` dependencies. Do this by navigating into the package directory and calling `pip install -e ".[docs]"`
+ 2. Navigate into the `/docs` directory and call `make html`. This will build the package documentation and place it in the `/docs/_build` directory.
+    - Note that when repeatedly building documentation, you should call `make clean` each time, followed by `make html`.
+ 3. Open the file `/docs/_build/html/index.html` in your browser. This is your site! Links to other pages in the site should all work, so you can explore the documentation here.
+
+## Workflows
+You package should contain (at least) these four workflows, which live in the [`.github/workflows`](/.github/workflows/) folder.
+
+
+### [`ci.yml`](/.github/workflows/ci.yml)
+
+CI stands for "continuous integration". This is the workflow that actually builds your python package. Any time there is either a push or a pull to the main branch of your repo, this workflow will run and build your package.
+
+Additionally, when you create a new version of your package (by making a new release) this workflow is responsible for deploying your latest version to PyPI.
+
+### [`build_docs.yml`](/.github/workflows/build_docs.yml)
+
+This workflow will build your package's documentation and deploy it online. This will be run any time that there is a push to the main branch of your repo. Note that this means that the online documentation may be "ahead" of the package version found on PyPI.
+
+### [`test_docs.yml`](/.github/workflows/test_docs.yml)
+
+This workflow is run on *pull requests* to the main branch. It builds your documentation, but does not deploy it online. This ensures that any changes made in your PR do not break the documentation.
+
+### [`cron.yml`](/.github/workflows/cron.yml)
+
+This workflow ensures that your package has not been broken by any unexpected changes to dependencies. You can configure it to run on a schedule.
+
+## Tests
+
+Yeah, testing! 

docs/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -T --color
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+watch:
+	sphinx-autobuild . _build/html --open-browser --watch examples

docs/api.md

@@ -0,0 +1,17 @@
+# Python API reference
+
+Python API can be easily documented with sphinx. For more information on all of the options, check out [sphinx's documentation](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html). The [reciprocalspaceship docs](https://github.com/rs-station/reciprocalspaceship/tree/main/docs) also do some clever things with sphinx.
+
+In the simplest form, the following code creates the documentation below for the entire module (in this case, all functions living inside the file `python_library.py`). You can include more of these blocks to document other modules as desired; you could also document different modules on different pages.
+
+```
+{eval-rst}
+.. automodule:: rs_template.python_library
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: rs_template.python_library
+   :members:
+
+```

docs/cli.md

@@ -0,0 +1,20 @@
+# CLI reference
+
+Command-line API can be easily and automatically documented by including an RST block. The code looks like this:
+
+```
+{eval-rst}
+.. autoprogram:: rs_template._command_line:create_parser()
+   :prog: rs.template
+
+```
+
+note that you need to direct `autoprogram` to a specific file and function which **returns an `argparse.ArgumentParser` object** (or to an `argparse.ArgumentParser` object itself).
+
+This will be rendered into your documentation:
+
+```{eval-rst}
+.. autoprogram:: rs_template._command_line:create_parser()
+   :prog: rs.template
+
+```