Docs setup simplification

This PR simplifies docs handling in the following ways 1. Register extra docs requirements in `setup.py` 2. Replace `builddocs.sh` with `README.md` 3. Avoid extra `sphinx_doc` directory
NOAA-GFDL · Feb 19, 2025 · b652ec9 · b652ec9
1 parent 73280b6
commit b652ec9
Show file tree

Hide file tree

Showing 18 changed files with 18 additions and 34 deletions.
diff --git a/docs/sphinx_doc/Makefile → docs/Makefile b/docs/sphinx_doc/Makefile → docs/Makefile
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,11 @@
+# NDSL docs
+
+This folder contains the NDSL documentation. For now, it is not automatically published. To build and view documentation locally,
+
+```bash
+make html
+```
+
+Then point your browser to the local html files in `_build/html` as mentioned in the build output.
+
+Be sure to include the `docs` extras when installing `NDSL`. The extra packages for docs are automatically included in the `develop` flavor.
diff --git a/docs/builddocs.sh b/docs/builddocs.sh
diff --git a/docs/sphinx_doc/conf.py → docs/conf.py b/docs/sphinx_doc/conf.py → docs/conf.py
diff --git a/docs/sphinx_doc/dace.rst → docs/dace.rst b/docs/sphinx_doc/dace.rst → docs/dace.rst
diff --git a/docs/sphinx_doc/developer_guide.rst → docs/developer_guide.rst b/docs/sphinx_doc/developer_guide.rst → docs/developer_guide.rst
diff --git a/docs/sphinx_doc/docker.rst → docs/docker.rst b/docs/sphinx_doc/docker.rst → docs/docker.rst
diff --git a/docs/sphinx_doc/fortran_porting.rst → docs/fortran_porting.rst b/docs/sphinx_doc/fortran_porting.rst → docs/fortran_porting.rst
diff --git a/docs/sphinx_doc/gt4py.rst → docs/gt4py.rst b/docs/sphinx_doc/gt4py.rst → docs/gt4py.rst
diff --git a/docs/sphinx_doc/index.rst → docs/index.rst b/docs/sphinx_doc/index.rst → docs/index.rst
diff --git a/docs/sphinx_doc/make.bat → docs/make.bat b/docs/sphinx_doc/make.bat → docs/make.bat
diff --git a/docs/sphinx_doc/overview.rst → docs/overview.rst b/docs/sphinx_doc/overview.rst → docs/overview.rst
diff --git a/docs/requirement_docs.txt b/docs/requirement_docs.txt
diff --git a/docs/sphinx_doc/static/ndsl_flow.png → docs/static/ndsl_flow.png b/docs/sphinx_doc/static/ndsl_flow.png → docs/static/ndsl_flow.png
diff --git a/.../sphinx_doc/static/ndsl_orchestration.png → docs/static/ndsl_orchestration.png b/.../sphinx_doc/static/ndsl_orchestration.png → docs/static/ndsl_orchestration.png
diff --git a/docs/sphinx_doc/test.rst → docs/test.rst b/docs/sphinx_doc/test.rst → docs/test.rst
diff --git a/docs/sphinx_doc/users_guide.rst → docs/users_guide.rst b/docs/sphinx_doc/users_guide.rst → docs/users_guide.rst
diff --git a/setup.py b/setup.py
@@ -10,15 +10,17 @@ def local_pkg(name: str, relative_path: str) -> str:
     path = f"{name} @ file://{Path(os.path.abspath(__file__)).parent / relative_path}"
     return path
 
-
-test_requirements = ["pytest", "pytest-subtests", "coverage"]
-develop_requirements = test_requirements + ["pre-commit"]
 demos_requirements = ["ipython", "ipykernel"]
+docs_requirements = ["recommonmark", "sphinx>=1.4", "sphinx-argparse", "sphinx_rtd_theme", "sphinx-gallery"]
+test_requirements = ["pytest", "pytest-subtests", "coverage"]
+
+develop_requirements = test_requirements + docs_requirements + ["pre-commit"]
 
 extras_requires = {
-    "test": test_requirements,
-    "develop": develop_requirements,
     "demos": demos_requirements,
+    "develop": develop_requirements,
+    "docs": docs_requirements,
+    "test": test_requirements,
 }
 
 requirements: List[str] = [