Fix: add info about hatch scripts

Author: lwasser

docs/conf.py

@@ -0,0 +1,66 @@
+# Below we grab the current date and time using python
+# this is used to them support the copyright date always being the current year
+# when you build your docs
+import subprocess
+from datetime import datetime
+
+current_year = datetime.now().year
+organization_name = "pyOpenSci"
+
+
+project = "pyosPackage"
+copyright = f"{current_year}, {organization_name}"
+author = "pyOpenSci Community"
+
+# *********** RELEASE NUMBER **************
+# This is optional - if you want the release of your docs to align with your
+# package release cycle then the code below will get the recent tag and use
+# that to generate your documentation release value.
+try:
+    release_value = (
+        subprocess.check_output(["git", "describe", "--tags"])
+        .decode("utf-8")
+        .strip()
+    )
+    release_value = release_value[:4]
+except subprocess.CalledProcessError:
+    release_value = "0.1"  # Default value in case there's no tag
+
+# Update the release value
+release = release_value
+
+
+release = "1.10"
+
+# -- General configuration ---------------------------------------------------
+# Extensions add additional functionality to your documentation.
+# TODO: describe each extension below
+extensions = [
+    "sphinx_design",
+    "sphinx_copybutton",
+    "sphinx.ext.intersphinx",
+    # This allows you to create :::{todo} sections that will not be rendered
+    # in the live docs
+    "sphinx.ext.todo",
+    "myst_parser",
+]
+
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# ****** setup MYST ******
+# colon fence for card support in md
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "attrs_block",
+]
+myst_heading_anchors = 3
+myst_footnote_transition = False
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]

docs/documentation/setup-sphinx.md

@@ -0,0 +1,51 @@
+# Sphinx documentation
+
+This package uses Sphinx to create documentation.
+
+We like sphinx because it is a community driven project with a community
+driven theme that the scientific Python community works on:
+
+`pydata_sphinx_theme`
+
+:::{note}
+MkDocs is the other most common documentation tool used in the Python
+ecosystem.
+:::
+
+## Setup your documentation
+
+You can chose to create sphinx documentation using sphinx-quickstart.
+Below is the Sphinx-quickstart workflow used to create these docs. However,
+inevitably you will likely customize the documentation setup. So you may also
+want to just copy this repository's structure.
+
+```
+➜ sphinx-quickstart
+Welcome to the Sphinx 5.3.0 quickstart utility.
+
+Please enter values for the following settings (just press Enter to
+accept a default value, if one is given in brackets).
+
+Selected root path: .
+
+You have two options for placing the build directory for Sphinx output.
+Either, you use a directory "_build" within the root path, or you separate
+"source" and "build" directories within the root path.
+> Separate source and build directories (y/n) [n]: n
+
+The project name will occur in several places in the built documentation.
+> Project name: pyosPackage
+> Author name(s): pyOpenSci Community
+> Project release []: 1.10
+
+If the documents are to be written in a language other than English,
+you can select a language here by its language code. Sphinx will then
+translate text that it generates into that language.
+
+For a list of supported codes, see
+https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
+> Project language [en]: en
+```
+
+The `conf.py` file is the core that you use to configure your sphinx docs.
+The conf.py file in this package is setup

docs/hatch-envs-scripts.md

@@ -0,0 +1,34 @@
+# Hatch scripts and environments
+
+* Hatch has a nox / tox / make like feature that allows you to:
+
+1. Define `Python` environments with a set of tools that you wish to have installed.
+2. Define commands that you wish to run in that environment.
+
+All of the configuration for this goes into your `pyproject.toml` file.
+
+## How to set this up
+
+To set this up you first need to define an environment in your `pyproject.toml`
+with all of the dependencies that the environment needs.
+
+Below you can see we have defined an environment called `docs`.
+
+:::{literalinclude} ../pyproject.toml
+:language: toml
+:start-at: [tool.hatch.envs.docs]
+:end-before: [tool.hatch.envs.docs.scripts]
+:::
+
+Once you have an environment setup, you can then create commands that you wish
+hatch to run for you within that environment. Below you setup two commands:
+
+1. Build sphinx docs using the `sphinx-build` command.
+2. Build sphinx docs in "live" mode which allows them to be updated every time
+that you save
+
+:::{literalinclude} ../pyproject.toml
+:language: toml
+:start-at: [tool.hatch.envs.docs.scripts]
+:end-before: [tool.hatch.envs.test]
+:::

docs/index.md

@@ -0,0 +1,32 @@
+# Welcome to pyosPackage's documentation
+
+:::{toctree}
+:maxdepth: 2
+:caption: Contents:
+
+home <self>
+hatch scripts <hatch-envs-scripts>
+Setup Sphinx <documentation/setup-sphinx>
+:::
+
+:::{toctree}
+:maxdepth: 2
+:caption: Contents:
+
+:::
+
+This guidebook uses myst as the primary documentation syntax.
+
+more about myst here....
+
+If you see syntax like the syntax below, you are looking at rst.
+
+```
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+```
+
+:::{note}
+you can remove the `make.bat` and `Makefile` files included with sphinx build.
+:::

pyproject.toml

@@ -30,6 +30,30 @@ Issues = "https://github.com/pyopensci/pyospackage/issues"
 Source = "https://github.com/pyopensci/pyospackage"
 
 
+[tool.hatch.envs.docs]
+dependencies = [
+  "sphinx",
+  "sphinx-autobuild",
+  "sphinx-inline-tabs",
+  # Note that the tool you install has dashes- between the name, vs _underscores
+  # when you call the theme in sphinx's conf.py
+  "pydata-sphinx-theme",
+  "sphinx-design",
+  "sphinx-copybutton",
+  "myst-nb",
+  "myst-parser",
+]
+
+
+[tool.hatch.envs.docs.scripts]
+# Build your docs statically - html output
+# hatch run docs:docs-html
+docs-html = "sphinx-build docs/ docs/_build"
+# hatch run docs:docs-html
+docs-live = "sphinx-autobuild docs/ docs/_build"
+# TODO: add step to clean docs directory
+
+
 [tool.hatch.envs.test]
 dependencies = [
   "pytest",