From 7476615f2c4182a153525db78e37e0ff9d8bab76 Mon Sep 17 00:00:00 2001 From: Massimiliano Lincetto Date: Mon, 26 Sep 2022 16:25:38 +0200 Subject: [PATCH 1/5] drop unused and deprecated files, move contributing guidelines to root --- .github/CONTRIBUTING.md => CONTRIBUTING.md | 0 docs/Makefile | 19 ------------ docs/make.bat | 35 ---------------------- docs/source/getting_started.rst | 4 --- 4 files changed, 58 deletions(-) rename .github/CONTRIBUTING.md => CONTRIBUTING.md (100%) delete mode 100644 docs/Makefile delete mode 100644 docs/make.bat delete mode 100644 docs/source/getting_started.rst diff --git a/.github/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 100% rename from .github/CONTRIBUTING.md rename to CONTRIBUTING.md diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 298ea9e2..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 27f573b8..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst deleted file mode 100644 index 0e18c25f..00000000 --- a/docs/source/getting_started.rst +++ /dev/null @@ -1,4 +0,0 @@ -Getting started -=============== - - From ba989ea9a0b32ba9a4a94141f9027aaeafa8fc60 Mon Sep 17 00:00:00 2001 From: Massimiliano Lincetto Date: Mon, 26 Sep 2022 16:26:00 +0200 Subject: [PATCH 2/5] git ignores docs build --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index d651e10f..fe547816 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ flarestack.egg-info *.pyc +docs/build \ No newline at end of file From abcdf6baed3dbfe354762fd643fd09b8b831099f Mon Sep 17 00:00:00 2001 From: Massimiliano Lincetto Date: Mon, 26 Sep 2022 16:26:21 +0200 Subject: [PATCH 3/5] update readme with build docs instruction --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 845183bd..91d5fe49 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ This will resolve your environment and install all dependencies. Another option is to use *pip* ```bash -pip install flarestack. +pip install flarestack ``` ### OPTION B: Actually, I want to see the backend code myself. Maybe I want to contribute to it! @@ -62,6 +62,11 @@ poetry install ``` This will install all packages as documented in the `poetry.lock` file. +If you want to also build the documentation locally, you should install the respective dependencies: + +```bash +poetry install --with docs +``` You can still use `pip` if you want to: From efea6c683dbcfeb3162ed3ba9d3dd1043883fc85 Mon Sep 17 00:00:00 2001 From: Massimiliano Lincetto Date: Mon, 26 Sep 2022 16:26:47 +0200 Subject: [PATCH 4/5] specify build language --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c0086b32..7d1436fa 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -89,7 +89,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. From cdebfda1105d4f106509dcc67b67d765573c4ebd Mon Sep 17 00:00:00 2001 From: Massimiliano Lincetto Date: Mon, 26 Sep 2022 16:28:41 +0200 Subject: [PATCH 5/5] update setup instructions --- docs/source/setup.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/source/setup.md b/docs/source/setup.md index 99bd3988..49a64d9c 100644 --- a/docs/source/setup.md +++ b/docs/source/setup.md @@ -84,6 +84,13 @@ export FLARESTACK_SCRATCH_DIR=/path/to/scratch A folder `flarestack__data` will be created in that directory. This is where you will find plots, pickle files and other files produced by the code. +## Building documentation +*flarestack* documentation is available at [Read the Docs](flarestack.readthedocs.io), however you may want to build it locally (especially if you are contributing to the project). To do this, run `sphinx-build` from the root directory of the repository: + +```bash +sphinx-build -b html docs/source/ docs/build/html +``` + ## Testing *flarestack* Is *flarestack* actually working? You can check the functionality of *flarestack* with *unit tests*. There are a suite of unit tests to cover *flarestack* functionality, which can be run from the base *flarestack* directory with: