update docs (#7)

Author: haileyajohnson

README.md

@@ -1,51 +1,5 @@
 # CDIPpy
 A python library for navigating and accessing CDIP products.
 
-## In this package
-_List of functions, WIP_  
-* data access
-*
-
-## Installation
-To install CDIPpy locally, you can either  
-1.  clone the repository, navigate to the root directory, and run `pip install .` or   
-2. without cloning the repositorym, install from github: `pip install git+https://github.com/cdipsw/CDIPpy.git`
-
-
-## Usage
-_Directions for use, WIP_
-
-## Development
-To set up a development copy of CDIPpy, install the project form source using `uv`:  
-``` bash
-pip install uv
-uv venv
-source activate .venv/bin/activate
-uv pip install -e .[dev]
-```
-This creates a local, virtual environment at `./.venv`, and installs a version of CDIPpy that is editable (`-e`), along with several additional dev dependencies (`[dev]`).
-
-### Testing
-This project uses python's built in `unittest` package. To run all tests: 
-~~~bash
-python -m unittest discover
-~~~
-To run with coverage:
-~~~bash
-coverage run -m unittest discover
-~~~
-To view the coverage report:
-~~~bash
-coverage report
-~~~
-
-### Contributing
-Contributions are welcome and should be merged via pull request on the `main` branch from a forked repository. Before a PR can be merged, it needs to pass the following checks:
-
-* all tests passed
-* coverage >= 90%
-* passes `flake8` linter
-* there must be at least one reviewer approval
-* a CLA must be signed by the contributor, if this is their first commit
-
-If you do not wish you manually check the style for every commit, there is a pre-commit hook that can do it for you. After setting up CDIPpy for development, install the hook with: `pre-commit install`. The installed hook will auto-format the files in your commit with `black` and check for any remaining format errors with `flake8`. 
+## Quick Start
+See the docs @ [https://cdipsw.github.io/CDIPpy/quickstart/](https://cdipsw.github.io/CDIPpy/quickstart/)

docs/examples/index.md

@@ -1,3 +1,2 @@
-# 🚧 **UNDER CONSTRUCTION** 🚧
 
-This section is still being developed.
+{{ under_construction("This section is still being developed.") }}

docs/index.md

@@ -1,7 +1,7 @@
 # CDIPpy
 CDIPpy is python library for navigating and accessing products provided by the [Coastal Data Information Program (CDIP)](https://cdip.ucsd.edu/m/about/) at Scripps Institution of Oceanography (SIO). It is a collection of utilities used within CDIP software operations that have useful potential for CDIP end-users as well.  
 
-A goal of publishing this library as an open source, contributable package is to foster closer collaboration between CDIP and the coommunity of users.
+A goal of publishing this library as an open source, contributable package is to foster closer collaboration between CDIP and the community of users.
 
 ## Navigating these docs
 The CDIP user community spans a brooad expertise and vastly different backgrounds in python development and usage - use the following guidelines to determine where to start in the documentation:  

docs/quickstart.md

@@ -1,25 +1,26 @@
 ## Installation
 To install CDIPpy locally, you can either  
 1.  clone the repository, navigate to the root directory, and run `pip install .` or   
-2. without cloning the repositorym, install from github: `pip install git+https://github.com/cdipsw/CDIPpy.git`
+2. without cloning the repository, install from github:  
+*https: `pip install git+https://github.com/cdipsw/CDIPpy.git`*  
+*ssh: `pip install git+ssh://github.com/cdipsw/CDIPpy.git`*
 
-🚧 **UNDER CONSTRUCTION** 🚧
-
-*TODO* add test snippet to check installation here
+{{ under_construction("add test snippet to check installation here") }}
 
 ---
 
-## Development
+## Development  
 To set up a development copy of CDIPpy, install the project form source using [`uv`](https://docs.astral.sh/uv/):  
 ``` bash
 >>> pip install uv
 >>> uv venv
 >>> source activate .venv/bin/activate
 >>> uv pip install -e .[dev]
 ```
+
 This creates a local, virtual environment at `./.venv`, and installs a version of CDIPpy that is editable (`-e`), along with several additional dev dependencies (`[dev]`).
----
 
+---
 ### Testing
 This project uses python's built in `unittest` package. To run all tests: 
 ~~~ bash

docs/user_guide/data_access.md

@@ -1,3 +1 @@
-# 🚧 **UNDER CONSTRUCTION** 🚧
-
-This page is still being written.
+{{ under_construction("This page is still being developed.") }}

docs/user_guide/index.md

@@ -5,8 +5,8 @@ This page contains instructions for CDIPpy users who just want to navigate, acce
 There are few options for installing `CDIPpy`:
 
 1) Install from PyPI (easiest):
-🚧 **UNDER CONSTRUCTION** 🚧  
-Publishing to PyPI would allow users to install with just `pip install cdippy  
+{{ under_construction("TODO: Publishing to PyPI would allow users to install with just `pip install cdippy`") }}
+
 
  2) Install from source (for developing or local control of library):  
  **Pre-requisite:** [`git`](https://git-scm.com/doc) must be installed  
@@ -19,7 +19,7 @@ Publishing to PyPI would allow users to install with just `pip install cdippy
 ---
 
 ## Contained in this library
-🚧 **UNDER CONSTRUCTION** 🚧
+{{ under_construction("This section is still being developed.") }}
 
 *TODO* Work on a comprehensive list of tools/features/uses of this library
 

docs/user_guide/plotting.md

@@ -1,3 +1 @@
-# 🚧 **UNDER CONSTRUCTION** 🚧
-
-This page is still being written.
+{{ under_construction("This page is still being written.") }}

main.py

@@ -0,0 +1,13 @@
+def define_env(env):
+    @env.macro
+    def under_construction(message="This section is under construction."):
+        return f"""
+<div style="border-radius:6px; overflow:hidden; margin:1em 0; font-family:inherit; box-shadow:0 1px 3px rgba(0,0,0,0.1);">
+  <div style="background-color:#FFA500; color:black; padding:10px 12px; font-weight:bold; font-size:1.1em;">
+    🚧 <strong>UNDER CONSTRUCTION</strong> 🚧
+  </div>
+  <div style="background-color:rgba(255, 165, 0, 0.15); color:black; padding:10px 12px;">
+    {message}
+  </div>
+</div>
+"""

mkdocs.yml

@@ -1,4 +1,8 @@
 site_name: CDIPpy Docs
+
+plugins:
+  - macros
+
 theme:
   name: readthedocs
 

pyproject.toml

@@ -24,6 +24,7 @@ dev = [
     "coverage",
     "flake8",
     "mkdocs",
+    "mkdocs-macros-plugin",
     "pre-commit"
 ]