From 56e34ab29916d0d6993dd664abd5025ee4bfae84 Mon Sep 17 00:00:00 2001 From: Vincent Sarago Date: Tue, 9 Apr 2024 16:02:03 +0200 Subject: [PATCH] refactor docs (#651) --- .github/workflows/deploy_mkdocs.yml | 9 +- CONTRIBUTING.md | 24 +-- docs/contributing.md | 1 - docs/index.md | 1 - mkdocs.yml => docs/mkdocs.yml | 8 +- docs/release-notes.md | 1 - docs/src/benchmarks.html | 292 +++++++++++++++++++++++++++ docs/src/contributing.md | 1 + docs/src/index.md | 1 + docs/src/release-notes.md | 1 + docs/{ => src}/stylesheets/extra.css | 0 docs/{ => src}/tips-and-tricks.md | 0 stac_fastapi/api/tests/benchmarks.py | 3 + 13 files changed, 320 insertions(+), 22 deletions(-) delete mode 120000 docs/contributing.md delete mode 120000 docs/index.md rename mkdocs.yml => docs/mkdocs.yml (97%) delete mode 120000 docs/release-notes.md create mode 100644 docs/src/benchmarks.html create mode 120000 docs/src/contributing.md create mode 120000 docs/src/index.md create mode 120000 docs/src/release-notes.md rename docs/{ => src}/stylesheets/extra.css (100%) rename docs/{ => src}/tips-and-tricks.md (100%) diff --git a/.github/workflows/deploy_mkdocs.yml b/.github/workflows/deploy_mkdocs.yml index b29f0732a..7132fdb6c 100644 --- a/.github/workflows/deploy_mkdocs.yml +++ b/.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,8 +27,8 @@ 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] \ @@ -37,7 +36,7 @@ jobs: - 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cadb694e9..c89495c3f 100644 --- a/CONTRIBUTING.md +++ b/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 ``` diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 120000 index 44fcc6343..000000000 --- a/docs/contributing.md +++ /dev/null @@ -1 +0,0 @@ -../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 120000 index 32d46ee88..000000000 --- a/docs/index.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/mkdocs.yml b/docs/mkdocs.yml similarity index 97% rename from mkdocs.yml rename to docs/mkdocs.yml index 60374dc3b..dff2035ca 100644 --- a/mkdocs.yml +++ b/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 diff --git a/docs/release-notes.md b/docs/release-notes.md deleted file mode 120000 index cf547089d..000000000 --- a/docs/release-notes.md +++ /dev/null @@ -1 +0,0 @@ -../CHANGES.md \ No newline at end of file diff --git a/docs/src/benchmarks.html b/docs/src/benchmarks.html new file mode 100644 index 000000000..f813e09b0 --- /dev/null +++ b/docs/src/benchmarks.html @@ -0,0 +1,292 @@ + + + + + + + Benchmarks + + + + +
+ + + + + + + diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 120000 index 000000000..f939e75f2 --- /dev/null +++ b/docs/src/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md new file mode 120000 index 000000000..fe8400541 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/docs/src/release-notes.md b/docs/src/release-notes.md new file mode 120000 index 000000000..8980b4a7a --- /dev/null +++ b/docs/src/release-notes.md @@ -0,0 +1 @@ +../../CHANGES.md \ No newline at end of file diff --git a/docs/stylesheets/extra.css b/docs/src/stylesheets/extra.css similarity index 100% rename from docs/stylesheets/extra.css rename to docs/src/stylesheets/extra.css diff --git a/docs/tips-and-tricks.md b/docs/src/tips-and-tricks.md similarity index 100% rename from docs/tips-and-tricks.md rename to docs/src/tips-and-tricks.md diff --git a/stac_fastapi/api/tests/benchmarks.py b/stac_fastapi/api/tests/benchmarks.py index 3a194057d..b1c6321d7 100644 --- a/stac_fastapi/api/tests/benchmarks.py +++ b/stac_fastapi/api/tests/benchmarks.py @@ -131,6 +131,7 @@ def f(p): ) benchmark.group = "Items With Model validation" if validate else "Items" + benchmark.name = "Items With Model validation" if validate else "Items" response = benchmark(f, params) assert response.status_code == 200 @@ -149,6 +150,7 @@ def f(): return client_no_validation.get("/collections/fake_collection") benchmark.group = "Collection With Model validation" if validate else "Collection" + benchmark.name = "Collection With Model validation" if validate else "Collection" response = benchmark(f) assert response.status_code == 200 @@ -167,6 +169,7 @@ def f(): return client_no_validation.get("/collections") benchmark.group = "Collections With Model validation" if validate else "Collections" + benchmark.name = "Collections With Model validation" if validate else "Collections" response = benchmark(f) assert response.status_code == 200