8000 DOC-309 | Remove Rest DocuBlocks and obsolete documentation tooling (… · arangodb/arangodb@c00aa21 · GitHub
[go: up one dir, main page]
Skip to content

Commit c00aa21

Browse files
Simran-BSimran-B
authored
DOC-309 | Remove Rest DocuBlocks and obsolete documentation tooling (#19764)
* 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 * Re-add accidentally removed line
1 parent a08de78 commit c00aa21

File tree

298 files changed

+74
-25260
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

298 files changed

+74
-25260
lines changed

‎.github/CODEOWNERS

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@
44
# `documentation-team` ownership
55
/Documentation/ @arangodb/team-documentation
66
/utils/*Documentation* @arangodb/team-documentation
7-
/utils/*Examples* @arangodb/team-documentation
8-
/utils/*Swagger* @arangodb/team-documentation
97

108
# `qa-team` ownership
119
/Installation/ @arangodb/team-qa

‎.gitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,6 @@ npm-debug.log
129129
/log-*
130130
data-*
131131
databases
132-
!/Documentation/DocuBlocks/Rest/Databases
133132
cluster-init
134133

135134
datafile-*.db

‎CHANGELOG

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
v3.10.11 (XXXX-XX-XX)
22
---------------------
33

4+
* Removed DocuBlocks and obsolete documentation tooling.
5+
The HTTP API descriptions are now in the `arangodb/docs-hugo` repository.
6+
47
* Fixed BTS-1556: Potential shutdown race, when the server is shutting down and
58
still AgencyCommunication was going on it could use the scheduler which was
69
already deleted, causing a crash right before a normal shutdown.
@@ -9419,8 +9422,6 @@ v3.5.0-rc.1 (2019-05-14)
94199422
- `--javascript.endpoints-whitelist`: control accessible endpoints in JavaScript
94209423
- `--javascript.files-whitelist`: control file access in JavaScript
94219424

9422-
Note: There is a [detailed description of all options](https://www.arangodb.com/docs/devel/security-security-options.html).
9423-
94249425
* Prevented arangod from making a call to www.arangodb.com at startup.
94259426

94269427
This call was done to check for available updates, but it could have contributed

‎CMakeLists.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -332,7 +332,7 @@ set(ARANGODB_PACKAGE_VENDOR "ArangoDB GmbH")
332332
set(ARANGODB_PACKAGE_CONTACT "info@arangodb.com")
333333
set(ARANGODB_DISPLAY_NAME "ArangoDB")
334334
set(ARANGODB_URL_INFO_ABOUT "https://www.arangodb.com")
335-
set(ARANGODB_HELP_LINK "https://www.arangodb.com/docs/${ARANGODB_VERSION_MAJOR}.${ARANGODB_VERSION_MINOR}/")
335+
set(ARANGODB_HELP_LINK "https://docs.arangodb.com/${ARANGODB_VERSION_MAJOR}.${ARANGODB_VERSION_MINOR}/")
336336
set(ARANGODB_CONTACT "hackers@arangodb.com")
337337
set(ARANGODB_FRIENDLY_STRING "ArangoDB - the native multi-model NoSQL database")
338338

‎CONTRIBUTING.md

Lines changed: 61 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ yet.
3030

3131
- If the modifications change any documented behavior or add new features,
3232
document the changes. It should be written in American English.
33-
The documentation can be found in [docs repository](https://github.com/arangodb/docs#readme).
33+
The documentation can be found in [`docs-hugo` repository](https://github.com/arangodb/docs-hugo#readme).
3434

3535
- When done, run the complete test suite and make sure all tests pass.
3636

@@ -232,10 +232,15 @@ favorite browser and open the web interface.
232232
All changes to any source will automatically re-build and reload your browser.
233233
Enjoy :)
234234

235-
### Cross Origin Policy (CORS) ERROR
235+
#### Cross Origin Policy (CORS) ERROR
236236

237-
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,
238-
we recently confirmed that this error occurs in ( Chrome v: 98.0.4758.102 and Firefox v: 96.0.1 ).
237+
Our front-end development server currently runs on port:`3000`, while the backend
238+
runs on port:`8529` respectively. This implies that when the front-end sends a
239+
request to the backend would result in Cross-Origin-Policy security checks which
240+
recently got enforced by some browsers for security reasons. Until recently, we
241+
never had reports of CORS errors when running both the backend and front-end dev
242+
servers independently, however, we recently confirmed that this error occurs in
243+
(Chrome version 98.0.4758.102 and Firefox version 96.0.1).
239244

240245
In case you run into CORS errors while running the development server, here is a quick fix:
241246

@@ -291,6 +296,58 @@ For example to commit a patch for the transitive dependency `is-wsl` of the depe
291296
and then run `npx patch-package node-netstat/is-wsl` in `js/node` and commit the resulting
292297
patch file in `js/node/patches`.
293298

299+
#### Build the HTTP API documentation for Swagger-UI
300+
301+
The REST HTTP API of the ArangoDB server is described using the OpenAPI
302+
specification (formerly Swagger). The source code is in documentation repository
303+
at <https://github.com/arangodb/docs-hugo>.
304+
305+
To build the `api-docs.json` file for viewing the API documentation in the
306+
Swagger-UI of the web interface (**SUPPORT** section, **Rest API** tab), run
307+
the following commands in a terminal:
308+
309+
1. Get a working copy of the documentation content with Git:
310+
311+
`git clone https://github.com/arangodb/docs-hugo`
312+
313+
2. Enter the `docs-hugo` folder:
314+
315+
`cd docs-hugo`
316+
317+
3. Optional: Switch to a tag, branch, or commit if you want to build the
318+
API documentation for a specific version of the docs:
319+
320+
`git checkout <reference>`
321+
322+
4. Enter the folder of the Docker toolchain, `amd64` on the x86-64 architecture
323+
and `arm64` on ARM CPUs:
324+
325+
```shell
326+
cd toolchain/docker/amd64 # x86-64
327+
cd toolchain/docker/arm64 # ARM 64-bit
328+
```
329+
330+
5. Set the environment variable `ENV` to any value other than `local` to make
331+
the documentation tooling not start a live server in watch mode but rather
332+
create and static build and exit:
333+
334+
```shell
335+
export ENV=static # Bash
336+
set -xg ENV static # Fish
337+
$Env:ENV='static' # PowerShell
338+
```
339+
340+
6. Run Docker Compose using the plain build configuration for the documentation:
341+
342+
`docker compose -f docker-compose.plain-build.yml up --abort-on-container-exit`
343+
344+
7. When the docs building finishes successfully, you can find the `api-docs.json`
345+
files in `site/data/<version>/`.
346+
347+
8. Copy the respective `api-docs.json` file into the ArangoDB working copy or
348+
installation folder under `js/apps/system/_admin/aardvark/APP/api-docs.json`
349+
and refresh the web interface.
350+
294351
---
295352

296353
## Running

‎Documentation/Books/AQL/.gitkeep

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎Documentation/Books/Drivers/.gitkeep

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎Documentation/Books/HTTP/.gitkeep

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎Documentation/Books/Manual/.gitkeep

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎Documentation/CMakeLists.txt

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,5 @@
11
# -*- mode: CMAKE; -*-
22

3-
# swagger
4-
add_custom_target(swagger
5-
COMMAND ${PROJECT_SOURCE_DIR}/utils/generateSwagger.sh
6-
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
7-
8-
# swagger
9-
add_custom_target(examples
10-
COMMAND ${PROJECT_SOURCE_DIR}/utils/generateExamples.sh
11-
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})
12-
133
# manual pages
144
set(MAN_NAMES
155
man1/arangobench.1
@@ -66,4 +56,3 @@ add_custom_target(clean_man_autogenerated
6656

6757
list(APPEND CLEAN_AUTOGENERATED_FILES clean_man_autogenerated)
6858
set(CLEAN_AUTOGENERATED_FILES ${CLEAN_AUTOGENERATED_FILES} PARENT_SCOPE)
69-

‎Documentation/DocuBlocks/Rest/Administration/delete_api_shutdown.md

Lines changed: 0 additions & 42 deletions
This file was deleted.

‎Documentation/DocuBlocks/Rest/Administration/get_admin_license.md

Lines changed: 0 additions & 51 deletions
This file was deleted.

‎Documentation/DocuBlocks/Rest/Administration/get_admin_server_availability.md

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎Documentation/DocuBlocks/Rest/Administration/get_admin_server_mode.md

Lines changed: 0 additions & 18 deletions
This file was deleted.

0 commit comments

Comments
 (0)
0