From 2d7230087aa515f9bba3004c94cb61a2287c17d6 Mon Sep 17 00:00:00 2001 From: jld3103 Date: Wed, 5 Apr 2023 12:49:16 +0200 Subject: [PATCH] Add new OCS API documentation Signed-off-by: jld3103 --- .gitignore | 7 +++++- .gitmodules | 3 +++ Makefile | 27 ++++++++++++++++++++-- build/openapi-extractor | 1 + developer_manual/_static/openapi.html | 10 ++++++++ developer_manual/client_apis/OCS/index.rst | 4 ++++ developer_manual/conf.py | 2 +- 7 files changed, 50 insertions(+), 4 deletions(-) create mode 100644 .gitmodules create mode 160000 build/openapi-extractor create mode 100644 developer_manual/_static/openapi.html diff --git a/.gitignore b/.gitignore index f5c18cb03da..b9196717abe 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,11 @@ _build developer_manual/html_css_design/img developer_manual/html_css_design/icons.txt +# OpenAPI file +developer_manual/_static/openapi.json +developer_manual/_static/stoplight-elements.js +developer_manual/_static/stoplight-elements.css + # Exclude Eclipse project .project @@ -47,4 +52,4 @@ venv .history/ # JetBrains IDEs -.idea/ \ No newline at end of file +.idea/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000000..783d98b5ca6 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "build/openapi-extractor"] + path = build/openapi-extractor + url = https://github.com/nextcloud/openapi-extractor diff --git a/Makefile b/Makefile index 9ea1b8106f3..0da2aed82f6 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,7 @@ user-manual-html: cd user_manual && make html @echo "User manual build finished; HTML is updated" -developer-manual-html: icons-docs +developer-manual-html: openapi-spec icons-docs rm -rf developer_manual/_build/html/com cd developer_manual && make html @echo "Developer manual build finished; HTML is updated" @@ -26,8 +26,31 @@ user-manual-pdf: cd user_manual && make latexpdf @echo "User manual build finished; PDF is updated" -icons-docs: clean-icons-docs +get-server-sources: cd build && sh get-server-sources.sh $(DRONE_BRANCH) + +openapi-spec: get-server-sources + git submodule update --init + cd build/openapi-extractor && composer install + cd build && ./openapi-extractor/merge-specs \ + --core server/core/openapi.json \ + --merged ../developer_manual/_static/openapi.json \ + server/apps/cloud_federation_api/openapi.json \ + server/apps/dashboard/openapi.json \ + server/apps/dav/openapi.json \ + server/apps/files_sharing/openapi.json \ + server/apps/oauth2/openapi.json \ + server/apps/provisioning_api/openapi.json \ + server/apps/settings/openapi.json \ + server/apps/theming/openapi.json \ + server/apps/user_status/openapi.json \ + server/apps/weather_status/openapi.json + cd developer_manual/_static && \ + wget https://unpkg.com/@stoplight/elements@7.7.17/web-components.min.js -O stoplight-elements.js && \ + wget https://unpkg.com/@stoplight/elements@7.7.17/styles.min.css -O stoplight-elements.css + + +icons-docs: clean-icons-docs get-server-sources cd build && composer install && composer update cd build && php generateIconsDoc.php diff --git a/build/openapi-extractor b/build/openapi-extractor new file mode 160000 index 00000000000..13d22c9cc3c --- /dev/null +++ b/build/openapi-extractor @@ -0,0 +1 @@ +Subproject commit 13d22c9cc3cbaa138d7268d48152b74bc4eeda33 diff --git a/developer_manual/_static/openapi.html b/developer_manual/_static/openapi.html new file mode 100644 index 00000000000..f32b3fa520c --- /dev/null +++ b/developer_manual/_static/openapi.html @@ -0,0 +1,10 @@ + + + OCS API + + + + + + + diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst index 00d7136b50a..5a3e0dd3a05 100644 --- a/developer_manual/client_apis/OCS/index.rst +++ b/developer_manual/client_apis/OCS/index.rst @@ -4,6 +4,10 @@ OCS API =============================== +To browse the new OCS API documentation please go `here <../../_static/openapi.html>`_. + +The old documentation is still kept as it provides some additional documentation that is not completely covered in the new documentation: + .. toctree:: ocs-api-overview diff --git a/developer_manual/conf.py b/developer_manual/conf.py index 30dab465777..3bee486887f 100644 --- a/developer_manual/conf.py +++ b/developer_manual/conf.py @@ -126,7 +126,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['../_shared_assets/static'] +html_static_path = ['../_shared_assets/static', '_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format.