Skip to content

Documentation restructure#189

Merged
rapids-bot[bot] merged 156 commits intoNVIDIA:developfrom
dagardner-nv:david-doc-restructure
May 14, 2025
Merged

Documentation restructure#189
rapids-bot[bot] merged 156 commits intoNVIDIA:developfrom
dagardner-nv:david-doc-restructure

Conversation

@dagardner-nv
Copy link
Contributor

@dagardner-nv dagardner-nv commented May 1, 2025

Description

  • Restructure documentation per feedback from the documentation team.
  • Section headings are no longer their own documents (that is they are not click-able)
    • Most TOCs are now in the root index.md file, section headings are defined with the :caption: directive
    • The exception being situations where a collapsible sub-section is desired.
  • Top-level TOCs are marked as :hidden: which prevents the TOC from being displayed in the page body while remaining visible in the side-bar.
  • Section headings have been renamed to be more aligned with documentation other Nvidia teams.
  • The "why-aiqtoolkit" has been merged into the root index.md document, as much of the information was repeated.
  • Consolidate the install and get-started documents into a single quick-start document.
  • This PR moves/renames most pieces of documentation, since this will represent the first release under the aiqtoolkit name we are technically not breaking any links.
  • Links in the top-level README.md file are no longer https links, and are now relative links into the ./docs/source dir. The reason is that any links to the official released documentation will always refer to the previous release, and the repo needs to be self-referential.
  • Links in pypi.md are now versioned links such that the links on https://pypi.org/project/aiqtoolkit/ will always link to the correct version of the documentation. The ci/release/update-version.sh script will update the version in these links.
  • In many cases where a document contained both an overview followed by more advanced/detailed information, these have been split into two documents. Ex: docs/source/components/retriever.md has been split into:
    • docs/source/store-and-retrieve/retrievers.md
    • docs/source/extend/adding-a-retriever.md
  • advanced has been replaced with extend and reference
  • The list of framework integrations has been moved from plugins.md to the installing.md file, as this information is needed by new-users. The rest of the plugins.md document was about authoring a plugin and is more advanced in nature.
  • The docs/source/guides/create-customize-workflows.md document is broken out into it's constituent parts and re-organized under docs/source/tutorials
  • Add Support and Licensing documents, previously these were sections within the contributing.md file
  • Extract the "Launching API Server and User Interface" section from the docs/source/guides/using-aiqtoolkit-ui-and-server.md guide, as this portion was new-user information, while the other portions were more advanced reference documentation.
  • The three Observability functions have been grouped together with the following structure:
    • Observe Workflows
      • Observing with Phoenix
      • Observing with W&B Weave

By Submitting this PR I confirm:

  • I am familiar with the Contributing Guidelines.
  • We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
    • Any contribution which contains commits that are not Signed-Off will not be accepted.
  • When the PR is ready for review, new or existing tests cover these changes.
  • When the PR is ready for review, the documentation is up to date with these changes.

Signed-off-by: David Gardner <dagardner@nvidia.com>
… linking to anchor tags in the toctree

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
…e References section, contributing CoC support and licensing are under Resources

Signed-off-by: David Gardner <dagardner@nvidia.com>
@dagardner-nv dagardner-nv added doc Improvements or additions to documentation skip-ci Optionally Skip CI for this PR breaking Breaking change labels May 1, 2025
@dagardner-nv dagardner-nv self-assigned this May 1, 2025
@dagardner-nv dagardner-nv marked this pull request as draft May 1, 2025 20:52
…structure

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
…start document

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
…structure

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
…ction

Signed-off-by: David Gardner <dagardner@nvidia.com>
…ction

Signed-off-by: David Gardner <dagardner@nvidia.com>
…er the get-started section

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
…o the Resources section

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
…structure

Signed-off-by: David Gardner <dagardner@nvidia.com>
…structure

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
…structure

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
…structure

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Copy link
Collaborator

@mdemoret-nv mdemoret-nv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like the "What AIQ is Not" section added back into the overview.

dagardner-nv and others added 16 commits May 13, 2025 17:04
Co-authored-by: Michael Demoret <42954918+mdemoret-nv@users.noreply.github.com>
Signed-off-by: David Gardner <96306125+dagardner-nv@users.noreply.github.com>
Co-authored-by: Michael Demoret <42954918+mdemoret-nv@users.noreply.github.com>
Signed-off-by: David Gardner <96306125+dagardner-nv@users.noreply.github.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Co-authored-by: lvojtku <lvojtku@nvidia.com>
Signed-off-by: David Gardner <96306125+dagardner-nv@users.noreply.github.com>
…IQ into david-doc-restructure

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Co-authored-by: lvojtku <lvojtku@nvidia.com>
Signed-off-by: David Gardner <96306125+dagardner-nv@users.noreply.github.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Co-authored-by: lvojtku <lvojtku@nvidia.com>
Signed-off-by: David Gardner <96306125+dagardner-nv@users.noreply.github.com>
Co-authored-by: lvojtku <lvojtku@nvidia.com>
Signed-off-by: David Gardner <96306125+dagardner-nv@users.noreply.github.com>
…IQ into david-doc-restructure

Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
@dagardner-nv
Copy link
Contributor Author

/merge

@rapids-bot rapids-bot bot merged commit 24590ae into NVIDIA:develop May 14, 2025
10 checks passed
@dagardner-nv dagardner-nv deleted the david-doc-restructure branch May 14, 2025 16:06
ericevans-nv pushed a commit to ericevans-nv/agent-iq that referenced this pull request Jun 3, 2025
* Restructure documentation per feedback from the documentation team.
* Section headings are no longer their own documents (that is they are not click-able)
  - Most TOCs are now in the root `index.md` file, section headings are defined with the `:caption:` directive
  - The exception being situations where a collapsible sub-section is desired.
* Top-level TOCs are marked as `:hidden:` which prevents the TOC from being displayed in the page body while remaining visible in the side-bar.
* Section headings have been renamed to be more aligned with documentation other Nvidia teams.
* The "why-aiqtoolkit" has been merged into the root `index.md` document, as much of the information was repeated.
* Consolidate the install and get-started documents into a single quick-start document.
* This PR moves/renames most pieces of documentation, since this will represent the first release under the `aiqtoolkit` name we are technically not breaking any links.
* Links in the top-level `README.md` file are no longer https links, and are now relative links into the `./docs/source` dir. The reason is that any links to the official released documentation will always refer to the previous release, and the repo needs to be self-referential.
* Links in `pypi.md` are now versioned links such that the links on https://pypi.org/project/aiqtoolkit/ will always link to the correct version of the documentation. The `ci/release/update-version.sh` script will update the version in these links.
* In many cases where a document contained both an overview followed by more advanced/detailed information, these have been split into two documents. Ex: `docs/source/components/retriever.md` has been split into:
  * `docs/source/store-and-retrieve/retrievers.md`
  * `docs/source/extend/adding-a-retriever.md`
* `advanced` has been replaced with `extend` and `reference`
* The list of framework integrations has been moved from `plugins.md` to the `installing.md` file, as this information is needed by new-users. The rest of the `plugins.md` document was about authoring a plugin and is more advanced in nature.
* The `docs/source/guides/create-customize-workflows.md` document is broken out into it's constituent parts and re-organized under `docs/source/tutorials`
* Add Support and Licensing documents, previously these were sections within the `contributing.md` file
* Extract the "Launching API Server and User Interface" section from the `docs/source/guides/using-aiqtoolkit-ui-and-server.md` guide, as this portion was new-user information, while the other portions were more advanced reference documentation.
* The three Observability functions have been grouped together with the following structure:
  - Observe Workflows
      - Observing with Phoenix
      - Observing with W&B Weave

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AIQToolkit/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - David Gardner (https://github.com/dagardner-nv)

Approvers:
  - https://github.com/lvojtku
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#189
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>
ericevans-nv pushed a commit to ericevans-nv/agent-iq that referenced this pull request Jun 3, 2025
* Restructure documentation per feedback from the documentation team.
* Section headings are no longer their own documents (that is they are not click-able)
  - Most TOCs are now in the root `index.md` file, section headings are defined with the `:caption:` directive
  - The exception being situations where a collapsible sub-section is desired.
* Top-level TOCs are marked as `:hidden:` which prevents the TOC from being displayed in the page body while remaining visible in the side-bar.
* Section headings have been renamed to be more aligned with documentation other Nvidia teams.
* The "why-aiqtoolkit" has been merged into the root `index.md` document, as much of the information was repeated.
* Consolidate the install and get-started documents into a single quick-start document.
* This PR moves/renames most pieces of documentation, since this will represent the first release under the `aiqtoolkit` name we are technically not breaking any links.
* Links in the top-level `README.md` file are no longer https links, and are now relative links into the `./docs/source` dir. The reason is that any links to the official released documentation will always refer to the previous release, and the repo needs to be self-referential.
* Links in `pypi.md` are now versioned links such that the links on https://pypi.org/project/aiqtoolkit/ will always link to the correct version of the documentation. The `ci/release/update-version.sh` script will update the version in these links.
* In many cases where a document contained both an overview followed by more advanced/detailed information, these have been split into two documents. Ex: `docs/source/components/retriever.md` has been split into:
  * `docs/source/store-and-retrieve/retrievers.md`
  * `docs/source/extend/adding-a-retriever.md`
* `advanced` has been replaced with `extend` and `reference`
* The list of framework integrations has been moved from `plugins.md` to the `installing.md` file, as this information is needed by new-users. The rest of the `plugins.md` document was about authoring a plugin and is more advanced in nature.
* The `docs/source/guides/create-customize-workflows.md` document is broken out into it's constituent parts and re-organized under `docs/source/tutorials`
* Add Support and Licensing documents, previously these were sections within the `contributing.md` file
* Extract the "Launching API Server and User Interface" section from the `docs/source/guides/using-aiqtoolkit-ui-and-server.md` guide, as this portion was new-user information, while the other portions were more advanced reference documentation.
* The three Observability functions have been grouped together with the following structure:
  - Observe Workflows
      - Observing with Phoenix
      - Observing with W&B Weave

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AIQToolkit/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - David Gardner (https://github.com/dagardner-nv)

Approvers:
  - https://github.com/lvojtku
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#189
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>
AnuradhaKaruppiah pushed a commit to AnuradhaKaruppiah/oss-agentiq that referenced this pull request Aug 4, 2025
* Restructure documentation per feedback from the documentation team. 
* Section headings are no longer their own documents (that is they are not click-able)
  - Most TOCs are now in the root `index.md` file, section headings are defined with the `:caption:` directive
  - The exception being situations where a collapsible sub-section is desired.
* Top-level TOCs are marked as `:hidden:` which prevents the TOC from being displayed in the page body while remaining visible in the side-bar.
* Section headings have been renamed to be more aligned with documentation other Nvidia teams.
* The "why-aiqtoolkit" has been merged into the root `index.md` document, as much of the information was repeated.
* Consolidate the install and get-started documents into a single quick-start document.
* This PR moves/renames most pieces of documentation, since this will represent the first release under the `aiqtoolkit` name we are technically not breaking any links.
* Links in the top-level `README.md` file are no longer https links, and are now relative links into the `./docs/source` dir. The reason is that any links to the official released documentation will always refer to the previous release, and the repo needs to be self-referential.
* Links in `pypi.md` are now versioned links such that the links on https://pypi.org/project/aiqtoolkit/ will always link to the correct version of the documentation. The `ci/release/update-version.sh` script will update the version in these links.
* In many cases where a document contained both an overview followed by more advanced/detailed information, these have been split into two documents. Ex: `docs/source/components/retriever.md` has been split into: 
  * `docs/source/store-and-retrieve/retrievers.md`
  * `docs/source/extend/adding-a-retriever.md`
* `advanced` has been replaced with `extend` and `reference`
* The list of framework integrations has been moved from `plugins.md` to the `installing.md` file, as this information is needed by new-users. The rest of the `plugins.md` document was about authoring a plugin and is more advanced in nature. 
* The `docs/source/guides/create-customize-workflows.md` document is broken out into it's constituent parts and re-organized under `docs/source/tutorials`
* Add Support and Licensing documents, previously these were sections within the `contributing.md` file
* Extract the "Launching API Server and User Interface" section from the `docs/source/guides/using-aiqtoolkit-ui-and-server.md` guide, as this portion was new-user information, while the other portions were more advanced reference documentation.
* The three Observability functions have been grouped together with the following structure:
  - Observe Workflows
      - Observing with Phoenix
      - Observing with W&B Weave


## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AIQToolkit/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - David Gardner (https://github.com/dagardner-nv)

Approvers:
  - https://github.com/lvojtku
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#189
scheckerNV pushed a commit to scheckerNV/aiq-factory-reset that referenced this pull request Aug 22, 2025
* Restructure documentation per feedback from the documentation team. 
* Section headings are no longer their own documents (that is they are not click-able)
  - Most TOCs are now in the root `index.md` file, section headings are defined with the `:caption:` directive
  - The exception being situations where a collapsible sub-section is desired.
* Top-level TOCs are marked as `:hidden:` which prevents the TOC from being displayed in the page body while remaining visible in the side-bar.
* Section headings have been renamed to be more aligned with documentation other Nvidia teams.
* The "why-aiqtoolkit" has been merged into the root `index.md` document, as much of the information was repeated.
* Consolidate the install and get-started documents into a single quick-start document.
* This PR moves/renames most pieces of documentation, since this will represent the first release under the `aiqtoolkit` name we are technically not breaking any links.
* Links in the top-level `README.md` file are no longer https links, and are now relative links into the `./docs/source` dir. The reason is that any links to the official released documentation will always refer to the previous release, and the repo needs to be self-referential.
* Links in `pypi.md` are now versioned links such that the links on https://pypi.org/project/aiqtoolkit/ will always link to the correct version of the documentation. The `ci/release/update-version.sh` script will update the version in these links.
* In many cases where a document contained both an overview followed by more advanced/detailed information, these have been split into two documents. Ex: `docs/source/components/retriever.md` has been split into: 
  * `docs/source/store-and-retrieve/retrievers.md`
  * `docs/source/extend/adding-a-retriever.md`
* `advanced` has been replaced with `extend` and `reference`
* The list of framework integrations has been moved from `plugins.md` to the `installing.md` file, as this information is needed by new-users. The rest of the `plugins.md` document was about authoring a plugin and is more advanced in nature. 
* The `docs/source/guides/create-customize-workflows.md` document is broken out into it's constituent parts and re-organized under `docs/source/tutorials`
* Add Support and Licensing documents, previously these were sections within the `contributing.md` file
* Extract the "Launching API Server and User Interface" section from the `docs/source/guides/using-aiqtoolkit-ui-and-server.md` guide, as this portion was new-user information, while the other portions were more advanced reference documentation.
* The three Observability functions have been grouped together with the following structure:
  - Observe Workflows
      - Observing with Phoenix
      - Observing with W&B Weave


## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AIQToolkit/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - David Gardner (https://github.com/dagardner-nv)

Approvers:
  - https://github.com/lvojtku
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#189
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking Breaking change doc Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants