Remove Rest DocuBlocks

* Remove Books and Examples placeholder folders * Remove scripts * Update link to docs repo * Docs: Add instructions for building api-docs.json with the new Docker Compose and Hugo-based documentation tooling The remaining links are covered by redirects for the time being * Misc cleanup, handle some of the doc links * Remove DocuBlock code comments * CHANGELOG entry
arangodb · KVS85 · Sep 15, 2023 · Sep 14, 2023 · Sep 14, 2023 · Sep 14, 2023
commit 59d5c32f495587fd5a5a872e210c81a9a6e92048
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -4,8 +4,6 @@
 # `documentation-team` ownership
 /Documentation/ @arangodb/team-documentation
 /utils/*Documentation* @arangodb/team-documentation
-/utils/*Examples* @arangodb/team-documentation
-/utils/*Swagger* @arangodb/team-documentation
 
 # `qa-team` ownership
 /Installation/ @arangodb/team-qa

diff --git a/.gitignore b/.gitignore
@@ -129,7 +129,6 @@ npm-debug.log
 /log-*
 data-*
 databases
-!/Documentation/DocuBlocks/Rest/Databases
 cluster-init
 
 datafile-*.db

diff --git a/CHANGELOG b/CHANGELOG
@@ -1,6 +1,9 @@
 v3.10.11 (XXXX-XX-XX)
 ---------------------
 
+* Removed DocuBlocks and obsolete documentation tooling.
+  The HTTP API descriptions are now in the `arangodb/docs-hugo` repository.
+
 * Fixed BTS-1556: Potential shutdown race, when the server is shutting down and
   still AgencyCommunication was going on it could use the scheduler which was
   already deleted, causing a crash right before a normal shutdown.
@@ -9419,8 +9422,6 @@ v3.5.0-rc.1 (2019-05-14)
   - `--javascript.endpoints-whitelist`: control accessible endpoints in JavaScript
   - `--javascript.files-whitelist`: control file access in JavaScript
 
-  Note: There is a [detailed description of all options](https://www.arangodb.com/docs/devel/security-security-options.html).
-
 * Prevented arangod from making a call to www.arangodb.com at startup.
 
   This call was done to check for available updates, but it could have contributed

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -332,7 +332,7 @@ set(ARANGODB_PACKAGE_VENDOR  "ArangoDB GmbH")
 set(ARANGODB_PACKAGE_CONTACT "info@arangodb.com")
 set(ARANGODB_DISPLAY_NAME    "ArangoDB")
 set(ARANGODB_URL_INFO_ABOUT  "https://www.arangodb.com")
-set(ARANGODB_HELP_LINK       "https://www.arangodb.com/docs/${ARANGODB_VERSION_MAJOR}.${ARANGODB_VERSION_MINOR}/")
+set(ARANGODB_HELP_LINK       "https://docs.arangodb.com/${ARANGODB_VERSION_MAJOR}.${ARANGODB_VERSION_MINOR}/")
 set(ARANGODB_CONTACT         "hackers@arangodb.com")
 set(ARANGODB_FRIENDLY_STRING "ArangoDB - the native multi-model NoSQL database")
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -30,7 +30,7 @@ yet.
 
 - If the modifications change any documented behavior or add new features,
   document the changes. It should be written in American English.
-  The documentation can be found in [docs repository](https://github.com/arangodb/docs#readme).
+  The documentation can be found in [`docs-hugo` repository](https://github.com/arangodb/docs-hugo#readme).
 
 - When done, run the complete test suite and make sure all tests pass.
 
@@ -232,10 +232,15 @@ favorite browser and open the web interface.
 All changes to any source will automatically re-build and reload your browser.
 Enjoy :)
 
-### Cross Origin Policy (CORS) ERROR
+#### Cross Origin Policy (CORS) ERROR
 
-Our front-end development server currently runs on port:`3000`, while the backend runs on port:`8529` respectively. This implies that when the front-end sends a request to the backend would result in Cross-Origin-Policy security checks which recently got enforced by some browsers for security reasons. Until recently, we never had reports of CORS errors when running both the backend and front-end dev servers independently, however,
-we recently confirmed that this error occurs in ( Chrome v: 98.0.4758.102 and Firefox v: 96.0.1 ).
+Our front-end development server currently runs on port:`3000`, while the backend
+runs on port:`8529` respectively. This implies that when the front-end sends a
+request to the backend would result in Cross-Origin-Policy security checks which
+recently got enforced by some browsers for security reasons. Until recently, we
+    never had reports of CORS errors when running both the backend and front-end dev
+servers independently, however, we recently confirmed that this error occurs in
+(Chrome version 98.0.4758.102 and Firefox version 96.0.1).
 
 In case you run into CORS errors while running the development server, here is a quick fix:
 
@@ -291,6 +296,58 @@ For example to commit a patch for the transitive dependency `is-wsl` of the depe
 and then run `npx patch-package node-netstat/is-wsl` in `js/node` and commit the resulting
 patch file in `js/node/patches`.
 
+#### Build the HTTP API documentation for Swagger-UI
+
+The REST HTTP API of the ArangoDB server is described using the OpenAPI
+specification (formerly Swagger). The source code is in documentation repository
+at <https://github.com/arangodb/docs-hugo>.
+
+To build the `api-docs.json` file for viewing the API documentation in the
+Swagger-UI of the web interface (**SUPPORT** section, **Rest API** tab), run
+the following commands in a terminal:
+
+1. Get a working copy of the documentation content with Git:
+
+   `git clone https://github.com/arangodb/docs-hugo`
+
+2. Enter the `docs-hugo` folder:
+
+   `cd docs-hugo`
+
+3. Optional: Switch to a tag, branch, or commit if you want to build the
+   API documentation for a specific version of the docs:
+
+   `git checkout <reference>`
+
+4. Enter the folder of the Docker toolchain, `amd64` on the x86-64 architecture
+   and `arm64` on ARM CPUs:
+
+   ```shell
+   cd toolchain/docker/amd64 # x86-64
+   cd toolchain/docker/arm64 # ARM 64-bit
+   ```
+
+5. Set the environment variable `ENV` to any value other than `local` to make
+   the documentation tooling not start a live server in watch mode but rather
+   create and static build and exit:
+
+   ```shell
+   export ENV=static  # Bash
+   set -xg ENV static # Fish
+   $Env:ENV='static'  # PowerShell
+   ```
+
+6. Run Docker Compose using the plain build configuration for the documentation:
+
+   `docker compose -f docker-compose.plain-build.yml up --abort-on-container-exit`
+
+7. When the docs building finishes successfully, you can find the `api-docs.json`
+   files in `site/data/<version>/`.
+
+8. Copy the respective `api-docs.json` file into the ArangoDB working copy or
+   installation folder under `js/apps/system/_admin/aardvark/APP/api-docs.json`
+   and refresh the web interface.
+
 ---
 
 ## Running

@@ -1,15 +1,5 @@
 # -*- mode: CMAKE; -*-
 
-# swagger
-add_custom_target(swagger
-  COMMAND ${PROJECT_SOURCE_DIR}/utils/generateSwagger.sh
-  WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
-
-# swagger
-add_custom_target(examples
-  COMMAND ${PROJECT_SOURCE_DIR}/utils/generateExamples.sh
-  WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
-
 # manual pages
 set(MAN_NAMES
   man1/arangobench.1
@@ -27,7 +17,6 @@ set(MAN_FILES "") #empty list
 
 
 foreach (m IN LISTS MAN_NAMES)
-    set(msrc ${CMAKE_SOURCE_DIR}/Documentation/${m})
     set(mdst ${CMAKE_CURRENT_BINARY_DIR}/man/${m})
 
   add_custom_command(
@@ -66,4 +55,3 @@ add_custom_target(clean_man_autogenerated
 
 list(APPEND CLEAN_AUTOGENERATED_FILES clean_man_autogenerated)
 set(CLEAN_AUTOGENERATED_FILES ${CLEAN_AUTOGENERATED_FILES} PARENT_SCOPE)
-