diff --git a/.gitignore b/.gitignore index d51d9650..582845f5 100644 --- a/.gitignore +++ b/.gitignore @@ -65,7 +65,8 @@ picamera_test_hashes.json *.log # Documentation -apidocs +apidocs/python +apidocs/http/*.json # PyBuilder target/ diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index f46e56af..7f20d205 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -180,11 +180,13 @@ build-docs: - | pydoctor -W \ --docformat restructuredtext \ + --html-output apidocs/python \ --project-name "OpenFlexure Microscope Server" \ --project-version $CI_COMMIT_REF_NAME \ --theme readthedocs \ --html-viewsource-base https://gitlab.com/openflexure/openflexure-microscope-server/-/tree/$CI_COMMIT_SHA/ \ src/openflexure_microscope_server + - ./generate_http_api_data.py - echo "JOB_ID=$CI_JOB_ID" > build-docs.env artifacts: expire_in: 1 week diff --git a/apidocs/http/index.html b/apidocs/http/index.html new file mode 100644 index 00000000..bb34ec7c --- /dev/null +++ b/apidocs/http/index.html @@ -0,0 +1,87 @@ + + + + OpenFlexure Microscope HTTP API Docs + + + + + + + + + +
+

OpenFlexure Microscope HTTP API

+ +

+ These docs are provided for reference only. They cannot control a running microscope. +

+ +

+ For interactive documentation on a live microscope, visit: +
+ http://microscope.local:5000/docs +

+ + +
+ +
+ + + + + + diff --git a/apidocs/index.html b/apidocs/index.html new file mode 100644 index 00000000..a3725b18 --- /dev/null +++ b/apidocs/index.html @@ -0,0 +1,60 @@ + + + + + +OpenFlexure Microscope Server API Docs + + + + + + + + +
+

OpenFlexure Microscope Server API Docs

+

Select documentation:

+ + HTTP API (Swagger) + Python API +
+ + + diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index feb32403..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -a -E -SPHINXBUILD = sphinx-build -SOURCEDIR = source -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 - -openapi: $(BUILDDIR)/swagger.yaml - -$(BUILDDIR)/swagger.yaml: Makefile - ofm-generate-openapi -o $@ - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -html dirhtml singlehtml json htmlhelp epub latex latexpdf text changes xml linkcheck doctest coverage clean: 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 b713a4e8..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,37 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -set SPHINXOPTS="-E" - -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/requirements.txt b/docs/requirements.txt deleted file mode 100644 index af0098a3..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,9 +0,0 @@ -sphinx_rtd_theme -numpy -labthings -expiringdict -sangaboard -typing_extensions -pillow -piexif -python-dateutil \ No newline at end of file diff --git a/generate_http_api_data.py b/generate_http_api_data.py new file mode 100755 index 00000000..86c09323 --- /dev/null +++ b/generate_http_api_data.py @@ -0,0 +1,52 @@ +#! /usr/bin/env python3 +"""Generate data about the HTTP API.""" + +import json +import os +from unittest import mock + +from fastapi.testclient import TestClient + +import labthings_fastapi as lt + +ROOT_DIR = os.path.dirname(os.path.abspath(__file__)) + + +def mock_picamera2_import() -> None: + """Mock the picamera2 library so that the full config can be loaded.""" + dummy_cam = mock.Mock() + mock_picamera2 = mock.MagicMock() + mock_picamera2.return_value.__enter__.return_value = dummy_cam + mock_picamera2.return_value.__exit__.return_value = None + mock.patch.dict( + "sys.modules", + { + "picamera2": mock_picamera2, + "picamera2.encoders": mock.Mock(), + "picamera2.outputs": mock.Mock(), + }, + ).start() + + +def main() -> None: + """Generate openapi description and Thing descriptions.""" + mock_picamera2_import() + config = os.path.join(ROOT_DIR, "ofm_config_full.json") + + with open(config, "r", encoding="utf-8") as file_obj: + config_dict = json.load(file_obj) + + config_dict["things"]["smart_scan"]["kwargs"]["scans_folder"] = "/tmp/scans" + + server = lt.ThingServer(things=config_dict["things"]) + test_client = TestClient(server.app) + td_response = test_client.get("/thing_descriptions/") + with open("apidocs/http/thing_descriptions.json", mode="w") as file_obj: + json.dump(td_response.json(), file_obj, indent=4) + openapi_response = test_client.get("/openapi.json") + with open("apidocs/http/openapi.json", mode="w") as f: + json.dump(openapi_response.json(), f, indent=4) + + +if __name__ == "__main__": + main()