|
@@ -22,7 +22,7 @@ The [Open 3D Engine (O3DE) API Reference](https://www.o3de.org/docs/api/) is gen
|
|
|
|
|
|
The C++ API reference generation scripts run Doxygen on your local `o3de` clone. These scripts output the generated files into your local `o3de.org` clone. Therefore, before you generate the API, you must ensure that your cloned repos are clean and have the latest changes.
|
|
The C++ API reference generation scripts run Doxygen on your local `o3de` clone. These scripts output the generated files into your local `o3de.org` clone. Therefore, before you generate the API, you must ensure that your cloned repos are clean and have the latest changes.
|
|
|
|
|
|
-#### `o3de`
|
|
|
|
|
|
+#### o3de and o3de-extras
|
|
|
|
|
|
1. In your local `o3de` clone, `git checkout` the latest updates in the `development` branch, or in the case of a major O3DE release, the `stabilization` branch.
|
|
1. In your local `o3de` clone, `git checkout` the latest updates in the `development` branch, or in the case of a major O3DE release, the `stabilization` branch.
|
|
|
|
|
|
@@ -30,11 +30,15 @@ The C++ API reference generation scripts run Doxygen on your local `o3de` clone.
|
|
git fetch --all
|
|
git fetch --all
|
|
git checkout upstream/<branch>
|
|
git checkout upstream/<branch>
|
|
```
|
|
```
|
|
- - **upstream**: Set to track the source repo, [`https://github.com/o3de/o3de.git`](https://github.com/o3de/o3de.git)
|
|
|
|
|
|
+ - **upstream**: Set to track the source repos
|
|
|
|
+ - o3de - [`https://github.com/o3de/o3de.git`](https://github.com/o3de/o3de.git)
|
|
|
|
+ - o3de-extras - [`https://github.com/o3de/o3de-extras.git`](https://github.com/o3de/o3de-extras.git)
|
|
|
|
|
|
-1. Make sure the branch is clean from any untracked files or changes. The branch should be at the same state as the upstream branch's HEAD. To clean, run `git clean`, `git reset`, or `git stash` as needed.
|
|
|
|
|
|
+2. Make sure the branch is clean from any untracked files or changes. The branch should be at the same state as the upstream branch's HEAD. To clean, run `git clean`, `git reset`, or `git stash` as needed.
|
|
|
|
+
|
|
|
|
+3. Repeat these steps with `o3de-extras`.
|
|
|
|
|
|
-#### `api.o3de.org`
|
|
|
|
|
|
+#### api.o3de.org
|
|
|
|
|
|
1. In your local `api.o3de.org` clone, `git checkout` the latest updates in the `development` branch, or in the case of a major O3DE release, the `stabilization` branch.
|
|
1. In your local `api.o3de.org` clone, `git checkout` the latest updates in the `development` branch, or in the case of a major O3DE release, the `stabilization` branch.
|
|
|
|
|
|
@@ -64,7 +68,7 @@ The C++ API reference generation scripts run Doxygen on your local `o3de` clone.
|
|
|
|
|
|
The C++ API reference generation scripts read from `O3DE_PATH` and write to `O3DEORG_PATH`.
|
|
The C++ API reference generation scripts read from `O3DE_PATH` and write to `O3DEORG_PATH`.
|
|
|
|
|
|
-1. If this is your first time running the script, you may need to enable permissions to execute the program. In the `o3de-doxygen` directory, run the following:
|
|
|
|
|
|
+2. If this is your first time running the script, you may need to enable permissions to execute the program. In the `o3de-doxygen` directory, run the following:
|
|
|
|
|
|
```shell
|
|
```shell
|
|
cd <path-to>/o3de-doxygen
|
|
cd <path-to>/o3de-doxygen
|
|
@@ -99,7 +103,21 @@ This generates the following files in `O3DEORG_PATH`:
|
|
- `content/gems/_index.md`
|
|
- `content/gems/_index.md`
|
|
- `gems/*`
|
|
- `gems/*`
|
|
|
|
|
|
|
|
+## Generating for Gems outside of `o3de`
|
|
|
|
|
|
|
|
+In some cases, the O3DE API Reference must include the API for code that lives outside of the `o3de` repository. This is typically decided by O3DE members and the Release Special Interest Group (SIG). For example, a major O3DE release may include new Gems that live in the `o3de-extras` repository.
|
|
|
|
+
|
|
|
|
+To generate API References for Gems outside of `o3de`:
|
|
|
|
+
|
|
|
|
+1. Move or copy the Gem's directory into the `Gems` directory of your local `o3de` clone.
|
|
|
|
+
|
|
|
|
+ To do this using the terminal in your Linux machine, run the following `cp` command with your specified paths. This copies the Gem into the `o3de/Gems/` directory.
|
|
|
|
+
|
|
|
|
+ ```shell
|
|
|
|
+ cp -r <path-to-gem> <path-to>/o3de/Gems
|
|
|
|
+ ```
|
|
|
|
+
|
|
|
|
+2. [Generate the Gems API](#gems-api).
|
|
|
|
|
|
## Publish
|
|
## Publish
|
|
|
|
|
|
@@ -121,23 +139,6 @@ Once the API docs are merged on GitHub, Hugo needs to know about the new version
|
|
If the main branch `api.o3de.org` has been updated beyond the version you need, it is possible to update the `go.mod` reference by hand, matching the existing format for the version. The first half of the version string is the commit date and time (`HHmmss`) in UTC, and the second half is the first 12 characters of the commit SHA. After saving the file, delete the `go.sum` file, if it exists, and run `hugo mod get` to make Hugo resync its data. Verify the update, then commit, push, and create or update the PR as needed.
|
|
If the main branch `api.o3de.org` has been updated beyond the version you need, it is possible to update the `go.mod` reference by hand, matching the existing format for the version. The first half of the version string is the commit date and time (`HHmmss`) in UTC, and the second half is the first 12 characters of the commit SHA. After saving the file, delete the `go.sum` file, if it exists, and run `hugo mod get` to make Hugo resync its data. Verify the update, then commit, push, and create or update the PR as needed.
|
|
|
|
|
|
|
|
|
|
-## Generating for Gems outside of `o3de`
|
|
|
|
-
|
|
|
|
-In some cases, the O3DE API Reference must include the API for code that lives outside of the `o3de` repository. This is typically decided by O3DE members and the Release Special Interest Group (SIG). For example, a major O3DE release may include new Gems that live in the `o3de-extras` repository.
|
|
|
|
-
|
|
|
|
-To generate API References for Gems outside of `o3de`:
|
|
|
|
-
|
|
|
|
-1. Move or copy the Gem's directory into the `Gems` directory of your local `o3de` clone.
|
|
|
|
-
|
|
|
|
- To do this using the terminal in your Linux machine, run the following `cp` command with your specified paths. This copies the Gem into the `o3de/Gems/` directory.
|
|
|
|
-
|
|
|
|
- ```shell
|
|
|
|
- cp -r <path-to-gem> <path-to>/o3de/Gems
|
|
|
|
- ```
|
|
|
|
-
|
|
|
|
-2. [Generate the Gems API](#gems-api).
|
|
|
|
-
|
|
|
|
-
|
|
|
|
## Customizing the API's main page
|
|
## Customizing the API's main page
|
|
|
|
|
|
The main page is the first page you see when you open a framework or Gem's Doxygen-generated API reference. For example, open any [framework](https://www.o3de.org/docs/api/frameworks/) or [Gem](https://www.o3de.org/docs/api/gems/) in the API docs. The contents of the main page is either automatically generated, or specified by the developer by using the Doxygen command, [\mainpage](https://doxygen.nl/manual/commands.html#cmdmainpage), in the code's comments.
|
|
The main page is the first page you see when you open a framework or Gem's Doxygen-generated API reference. For example, open any [framework](https://www.o3de.org/docs/api/frameworks/) or [Gem](https://www.o3de.org/docs/api/gems/) in the API docs. The contents of the main page is either automatically generated, or specified by the developer by using the Doxygen command, [\mainpage](https://doxygen.nl/manual/commands.html#cmdmainpage), in the code's comments.
|