refactor docs (#651)

.github/workflows/deploy_mkdocs.yml

@@ -8,7 +8,6 @@ on:
       # Rebuild website when docs have changed or code has changed
       - "README.md"
       - "docs/**"
-      - "mkdocs.yml"
       - "**.py"
   workflow_dispatch:
 
@@ -28,16 +27,16 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install --upgrade pip
-          pip install \
+          python -m pip install --upgrade pip
+          python -m pip install \
             stac_fastapi/api[docs] \
             stac_fastapi/types[docs] \
             stac_fastapi/extensions[docs] \
 
       - name: update API docs
         run: |
           pdocs as_markdown \
-            --output_dir docs/api/ \
+            --output_dir docs/src/api/ \
             --exclude_source \
             --overwrite \
             stac_fastapi
@@ -51,4 +50,4 @@ jobs:
           POSTGRES_HOST_WRITER: localhost
 
       - name: Deploy docs
-        run: mkdocs gh-deploy --force
+        run: mkdocs gh-deploy --force -f docs/mkdocs.yml

CONTRIBUTING.md

@@ -5,31 +5,31 @@ Issues and pull requests are more than welcome.
 **dev install**
 
 ```bash
-$ git clone https://github.com/stac-utils/stac-fastapi.git
-$ cd stac-fastapi
-$ pip install -e stac_fastapi/api[dev]
+git clone https://github.com/stac-utils/stac-fastapi.git
+cd stac-fastapi
+python -m pip install -e stac_fastapi/api[dev]
 ```
 
-**Python3.8 only**
+**pre-commit**
 
-This repo is set to use `pre-commit` to run *ruff*, *pydocstring*, *black* ("uncompromising Python code formatter") and mypy when committing new code.
+This repo is set to use `pre-commit` to run *ruff*, *pydocstring* and mypy when committing new code.
 
 ```bash
-$ pre-commit install
+pre-commit install
 ```
 
 ### Docs
 
 ```bash
-$ git clone https://github.com/stac-utils/stac-fastapi.git
-$ cd stac-fastapi
-$ pip install -e stac_fastapi/api["docs"]
+git clone https://github.com/stac-utils/stac-fastapi.git
+cd stac-fastapi
+python pip install -e stac_fastapi/api["docs"]
 ```
 
 Hot-reloading docs:
 
 ```bash
-$ mkdocs serve
+$ mkdocs serve -f docs/mkdocs.yml
 ```
 
 To manually deploy docs (note you should never need to do this because GitHub
@@ -38,11 +38,11 @@ Actions deploys automatically for new commits.):
 ```bash
 Create API documentations
 $ pdocs as_markdown \
-  --output_dir docs/api/ \
+  --output_dir docs/src/api/ \
   --exclude_source \
   --overwrite \
   stac_fastapi
 
 # deploy
-$ mkdocs gh-deploy
+$ mkdocs gh-deploy -f docs/mkdocs.yml
 ```

mkdocs.yml → docs/mkdocs.yml

@@ -4,7 +4,10 @@ site_description: STAC FastAPI.
 # Repository
 repo_name: "stac-utils/stac-fastapi"
 repo_url: "https://github.com/stac-utils/stac-fastapi"
-edit_uri: "blob/master/docs/src/"
+edit_uri: "blob/main/docs/src/"
+
+docs_dir: 'src'
+site_dir: 'build'
 
 # Social links
 extra:
@@ -15,6 +18,7 @@ extra:
 # Layout
 nav:
   - Home: "index.md"
+  - Tips and Tricks: tips-and-tricks.md
   - API:
       - packages: api/stac_fastapi/index.md
       - stac_fastapi.api:
@@ -70,9 +74,9 @@ nav:
           - search: api/stac_fastapi/types/search.md
           - stac: api/stac_fastapi/types/stac.md
           - version: api/stac_fastapi/types/version.md
+  - Performance Benchmarks: benchmarks.html
   - Development - Contributing: "contributing.md"
   - Release Notes: "release-notes.md"
-  - Tips and Tricks: tips-and-tricks.md
 
 plugins:
   - search