Update documentation to allow rendering with Sphinx.

piotrm0 · Apr 1, 2024 · 8b1d1bf · 8b1d1bf
1 parent c12593e
commit 8b1d1bf
Show file tree

Hide file tree

Showing 59 changed files with 432 additions and 88 deletions.
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -0,0 +1,9 @@
+.swagger-ui code {
+    white-space: pre-wrap;
+}
+
+.microlight code {
+    color: white;
+    background: none;
+    border: none;
+}
diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst
@@ -0,0 +1,7 @@
+Architecture
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   README
diff --git a/docs/evaluation/index.rst b/docs/evaluation/index.rst
@@ -0,0 +1,10 @@
+:orphan:
+
+Evaluation
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   README
+   llm-vulnerability-scanning
diff --git a/docs/evaluation/llm-vulnerability-scanning.md b/docs/evaluation/llm-vulnerability-scanning.md
@@ -53,4 +53,4 @@ At the same time, this experiment does not investigate if the guardrails also bl
 
 ## LLM Vulnerability Categories
 
-If you are interested in additional information about each vulnerability category in Garak, please consult the full results [here](./../_static/html/) and the [Garak GitHub](https://github.com/leondz/garak/) page.
+If you are interested in additional information about each vulnerability category in Garak, please consult the full results [here](./../_static/html/README.md) and the [Garak GitHub](https://github.com/leondz/garak/) page.
diff --git a/docs/getting_started/1_hello_world/index.rst b/docs/getting_started/1_hello_world/index.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+1 Hello World
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   README
diff --git a/docs/getting_started/2_core_colang_concepts/README.md b/docs/getting_started/2_core_colang_concepts/README.md
@@ -224,7 +224,7 @@ The prompt has four logical sections:
 
 2. A sample conversation, which can also be [configured](../../user_guides/configuration-guide.md#sample-conversation) using the `sample_conversation` key in *config.yml*.
 
-3. A set of examples for converting user utterances to canonical forms. The top five most relevant examples are chosen by performing a vector search against all the user message examples. For more details see [ABC Bot](../../../examples/bots/abc).
+3. A set of examples for converting user utterances to canonical forms. The top five most relevant examples are chosen by performing a vector search against all the user message examples. For more details see [ABC Bot](../../../examples/bots/abc/README.md).
 
 4. The current conversation preceded by the first two turns from the sample conversation.
 
@@ -327,4 +327,4 @@ This guide provides a detailed overview of two core Colang concepts: *messages*
 
 ## Next
 
-The next guide, [Demo Use Case](../3_demo_use_case), guides you through selecting a demo use case to implement different types of rails, such as for input, output, or dialog.
+The next guide, [Demo Use Case](../3_demo_use_case/README.md), guides you through selecting a demo use case to implement different types of rails, such as for input, output, or dialog.
diff --git a/docs/getting_started/2_core_colang_concepts/index.rst b/docs/getting_started/2_core_colang_concepts/index.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+2 Core Colang Concepts
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   README
diff --git a/docs/getting_started/3_demo_use_case/README.md b/docs/getting_started/3_demo_use_case/README.md
@@ -4,11 +4,11 @@ This topic describes a use case used in the remaining guide topics. The use case
 
 The following guide topics lead you through a step-by-step configuration process, addressing various challenges that might arise.
 
-1. [Input moderation](../4_input_rails): Verify that any user input is safe before proceeding.
-2. [Output moderation](../5_output_rails): Ensure that the bot's output is not offensive and does not include specific words.
-3. [Preventing off-topic questions](../6_topical_rails): Guarantee that the bot only responds to specific topics.
-4. [Retrieval augmented generation](../7_rag): Integrate external knowledge bases.
+1. [Input moderation](../4_input_rails/README.md): Verify that any user input is safe before proceeding.
+2. [Output moderation](../5_output_rails/README.md): Ensure that the bot's output is not offensive and does not include specific words.
+3. [Preventing off-topic questions](../6_topical_rails/README.md): Guarantee that the bot only responds to specific topics.
+4. [Retrieval augmented generation](../7_rag/README.md): Integrate external knowledge bases.
 
 ## Next
 
-Start with adding [Input Moderation](../4_input_rails) to the ABC Bot.
+Start with adding [Input Moderation](../4_input_rails/README.md) to the ABC Bot.
diff --git a/docs/getting_started/3_demo_use_case/index.rst b/docs/getting_started/3_demo_use_case/index.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+3 Demo Use Case
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   README
diff --git a/docs/getting_started/4_input_rails/README.md b/docs/getting_started/4_input_rails/README.md
@@ -1,6 +1,6 @@
 # Input Rails
 
-This topic demonstrates how to add input rails to a guardrails configuration. As discussed in the previous guide, [Demo Use Case](../3_demo_use_case), this topic guides you through building the ABC Bot.
+This topic demonstrates how to add input rails to a guardrails configuration. As discussed in the previous guide, [Demo Use Case](../3_demo_use_case/README.md), this topic guides you through building the ABC Bot.
 
 ## Prerequisites
 
@@ -105,7 +105,7 @@ Summary: 1 LLM call(s) took 0.92 seconds and used 106 tokens.
 1. Task `general` took 0.92 seconds and used 106 tokens.
 ```
 
-The summary shows that a single call was made to the LLM using the prompt for the task `general`. In contrast to the [Core Colang Concepts guide](../2_core_colang_concepts), where the `generate_user_intent` task is used as a first phase for each user message, if no user canonical forms are defined for the Guardrails configuration, the `general` task is used instead. Take a closer look at the prompt and the completion:
+The summary shows that a single call was made to the LLM using the prompt for the task `general`. In contrast to the [Core Colang Concepts guide](../2_core_colang_concepts/README.md), where the `generate_user_intent` task is used as a first phase for each user message, if no user canonical forms are defined for the Guardrails configuration, the `general` task is used instead. Take a closer look at the prompt and the completion:
 
 ```python
 print(info.llm_calls[0].prompt)
@@ -364,4 +364,4 @@ Input rails also have the ability to alter the message from the user. By changin
 
 ## Next
 
-The next guide, [Output Rails](../5_output_rails), adds output moderation to the bot.
+The next guide, [Output Rails](../5_output_rails/README.md), adds output moderation to the bot.
diff --git a/docs/getting_started/4_input_rails/index.rst b/docs/getting_started/4_input_rails/index.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+4 Input Rails
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   README
diff --git a/docs/getting_started/5_output_rails/README.md b/docs/getting_started/5_output_rails/README.md
@@ -1,6 +1,6 @@
 # Output Rails
 
-This guide describes how to add output rails to a guardrails configuration. This guide builds on the previous guide, [Input Rails](../4_input_rails), developing further the demo ABC Bot.
+This guide describes how to add output rails to a guardrails configuration. This guide builds on the previous guide, [Input Rails](../4_input_rails/README.md), developing further the demo ABC Bot.
 
 ## Prerequisites
 
@@ -292,4 +292,4 @@ I cannot talk about proprietary technology.
 
 ## Next
 
-The next guide, [Topical Rails](../6_topical_rails), adds a topical rails to the ABC bot, to make sure it only responds to questions related to the employment situation.
+The next guide, [Topical Rails](../6_topical_rails/README.md), adds a topical rails to the ABC bot, to make sure it only responds to questions related to the employment situation.
diff --git a/docs/getting_started/5_output_rails/index.rst b/docs/getting_started/5_output_rails/index.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+5 Output Rails
+==============
+
+.. toctree::
+   :maxdepth: 2
+
+   README
diff --git a/docs/getting_started/6_topical_rails/README.md b/docs/getting_started/6_topical_rails/README.md
@@ -1,6 +1,6 @@
 # Topical Rails
 
-This guide will teach you what *topical rails* are and how to integrate them into your guardrails configuration. This guide builds on the [previous guide](../5_output_rails), developing further the demo ABC Bot.
+This guide will teach you what *topical rails* are and how to integrate them into your guardrails configuration. This guide builds on the [previous guide](../5_output_rails/README.md), developing further the demo ABC Bot.
 
 ## Prerequisites
 

diff --git a/docs/getting_started/6_topical_rails/index.rst b/docs/getting_started/6_topical_rails/index.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+6 Topical Rails
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   README
diff --git a/docs/getting_started/7_rag/README.md b/docs/getting_started/7_rag/README.md
@@ -1,6 +1,6 @@
 # Retrieval-Augmented Generation
 
-This guide shows how to apply a guardrails configuration in a RAG scenario. This guide builds on the [previous guide](../6_topical_rails), developing further the demo ABC Bot.
+This guide shows how to apply a guardrails configuration in a RAG scenario. This guide builds on the [previous guide](../6_topical_rails/README.md), developing further the demo ABC Bot.
 
 ## Prerequisites
 
@@ -99,7 +99,7 @@ There are three ways you can configure a knowledge base directly into a guardrai
 2. Using a custom `retrieve_relevant_chunks` action.
 3. Using a custom `EmbeddingSearchProvider`.
 
-For option 1, you can add a knowledge base directly into your guardrails configuration by creating a *kb* folder inside the *config* folder and adding documents there. Currently, only the Markdown format is supported. For a quick example, check out the complete implementation of the [ABC Bot](../../../examples/bots/abc).
+For option 1, you can add a knowledge base directly into your guardrails configuration by creating a *kb* folder inside the *config* folder and adding documents there. Currently, only the Markdown format is supported. For a quick example, check out the complete implementation of the [ABC Bot](../../../examples/bots/abc/README.md).
 
 Options 2 and 3 represent advanced use cases beyond the scope of this topic.
 

diff --git a/docs/getting_started/7_rag/index.rst b/docs/getting_started/7_rag/index.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+7 Rag
+=====
+
+.. toctree::
+   :maxdepth: 2
+
+   README
diff --git a/docs/getting_started/README.md b/docs/getting_started/README.md
@@ -1,11 +1,24 @@
 # Getting Started
 
+```{toctree}
+:hidden:
+:maxdepth: 2
+:caption: Contents
+
+1_hello_world/README
+2_core_colang_concepts/README
+3_demo_use_case/README
+4_input_rails/README
+5_output_rails/README
+6_topical_rails/README
+7_rag/README
+```
 This *Getting Started* section of the documentation is meant to help you get started with NeMo Guardrails. It is structured as a sequence of guides focused on specific topics. Each guide builds on the previous one by introducing new concepts and features. For each guide, in addition to the README, you will find a corresponding Jupyter notebook and the final configuration (*config.yml*) in the *config* folder.
 
 1. [Hello World](./1_hello_world/README.md): get started with the basics of NeMo Guardrails by building a simple rail that controls the greeting behavior.
 2. [Core Colang Concepts](./2_core_colang_concepts/README.md): learn about the core concepts of Colang: messages and flows.
-3. [Demo Use Case](./3_demo_use_case): the choice of a representative use case.
-4. [Input moderation](./4_input_rails): make sure the input from the user is safe, before engaging with it.
-5. [Output moderation](./5_output_rails): make sure the output of the bot is not offensive and making sure it does not contain certain words.
-6. [Preventing off-topic questions](./6_topical_rails): make sure that the bot responds only to a specific set of topics.
-7. [Retrieval Augmented Generation](./7_rag): integrate an external knowledge base.
+3. [Demo Use Case](./3_demo_use_case/README.md): the choice of a representative use case.
+4. [Input moderation](./4_input_rails/README.md): make sure the input from the user is safe, before engaging with it.
+5. [Output moderation](./5_output_rails/README.md): make sure the output of the bot is not offensive and making sure it does not contain certain words.
+6. [Preventing off-topic questions](./6_topical_rails/README.md): make sure that the bot responds only to a specific set of topics.
+7. [Retrieval Augmented Generation](./7_rag/README.md): integrate an external knowledge base.
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
@@ -0,0 +1,22 @@
+:orphan:
+
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   installation-guide
+   README
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   1_hello_world/index
+   2_core_colang_concepts/index
+   3_demo_use_case/index
+   4_input_rails/index
+   5_output_rails/index
+   6_topical_rails/index
+   7_rag/index
diff --git a/docs/getting_started/installation-guide.md b/docs/getting_started/installation-guide.md
@@ -122,6 +122,6 @@ NeMo Guardrails can also be used through Docker. For details on how to build and
 
 ## What's next?
 
-* Check out the [Getting Started Guide](../getting_started) and start with the ["Hello World" example](../getting_started/1_hello_world).
-* Explore more examples in the [examples](../../examples) folder.
-* Review the [User Guides](../user_guides).
+* Check out the [Getting Started Guide](../getting_started/README.md) and start with the ["Hello World" example](../getting_started/1_hello_world/README.md).
+* Explore more examples in the [examples](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/examples) folder.
+* Review the [User Guides](../README.md).
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,90 @@
+NVIDIA NeMo Guardrails
+====================================================
+
+.. toctree::
+   :caption: NVIDIA NeMo Guardrails
+   :name: NVIDIA NeMo Guardrails
+   :maxdepth: 1
+
+   introduction.md
+   documentation.md
+   getting_started/installation-guide
+
+.. toctree::
+   :caption: Getting Started
+   :name: Getting Started
+   :maxdepth: 2
+
+   getting_started/1_hello_world/README
+   getting_started/2_core_colang_concepts/README
+   getting_started/3_demo_use_case/README
+   getting_started/4_input_rails/README
+   getting_started/5_output_rails/README
+   getting_started/6_topical_rails/README
+   getting_started/7_rag/README
+
+
+.. toctree::
+   :caption: User Guides
+   :name: User Guides
+   :maxdepth: 2
+
+   user_guides/cli
+   user_guides/colang-language-syntax-guide
+   user_guides/configuration-guide
+   user_guides/guardrails-library
+   user_guides/guardrails-process
+   user_guides/llm-support
+   user_guides/python-api
+   user_guides/server-guide
+   user_guides/detailed_logging/index
+   user_guides/input_output_rails_only/index
+   user_guides/jailbreak_detection_heuristics/index
+   user_guides/langchain/index
+   user_guides/llm/index
+   user_guides/multi_config_api/index
+
+.. toctree::
+   :caption: Evaluation
+   :name: Evaluation
+   :maxdepth: 2
+
+   evaluation/README
+   evaluation/llm-vulnerability-scanning
+
+.. toctree::
+   :caption: Security
+   :name: Security
+   :maxdepth: 2
+
+   security/guidelines
+   security/red-teaming
+
+.. toctree::
+   :caption: Advanced User Guides
+   :name: Advanced User Guides
+   :maxdepth: 2
+
+   user_guides/advanced/align-score-deployment
+   user_guides/advanced/bot-message-instructions
+   user_guides/advanced/embedding-search-providers
+   user_guides/advanced/event-based-api
+   user_guides/advanced/extract-user-provided-values
+   user_guides/advanced/generation-options
+   user_guides/advanced/jailbreak-detection-heuristics-deployment
+   user_guides/advanced/llama-guard-deployment
+   user_guides/advanced/nested-async-loop
+   user_guides/advanced/prompt-customization
+   user_guides/advanced/streaming
+   user_guides/advanced/using-docker
+   user_guides/advanced/vertexai-setup
+
+.. toctree::
+   :caption: Other
+   :name: Other
+   :maxdepth: 2
+
+   architecture/index
+   glossary
+   faqs
+   changes
diff --git a/docs/security/guidelines.md b/docs/security/guidelines.md
@@ -92,7 +92,7 @@ Like with a web server, red-teaming and testing at the scale of the web is a req
 
 AI safety and security is a community effort, and this is one of the main reasons we have released NeMo Guardrails to the community. We hope to bring many developers and enthusiasts together to build better solutions for Trustworthy AI. Our initial release is a starting point. We have built a collection of guardrails and educational examples that provide helpful controls and resist a variety of common attacks, however, they are not perfect. We have conducted adversarial testing on these example bots and will soon release a whitepaper on a larger-scale study. Here are some items to watch out for when creating your own bots:
 
-1. Over-aggressive moderation: Some of the AI Safety rails, such as [moderation](../../examples/moderation_rail/README.md) and [fact-checking](../../examples/grounding_rail/README.md), can occasionally block otherwise safe requests. This is more likely to happen when multiple guardrails are used together. One possible strategy to resolve this is to use logic in the flow to reduce unnecessary calls; for example to call fact-checking only for factual questions.
+1. Over-aggressive moderation: Some of the AI Safety rails, can occasionally block otherwise safe requests. This is more likely to happen when multiple guardrails are used together. One possible strategy to resolve this is to use logic in the flow to reduce unnecessary calls; for example to call fact-checking only for factual questions.
 2. Overgeneralization of canonical forms: NeMo Guardrails uses canonical forms like `ask about jobs report` to guide its behavior and to generalize to situations not explicitly defined in the Colang configuration. It may occasionally get the generalization wrong, so that guardrails miss certain examples or trigger unexpectedly. If this happens, it can often be improved by adding or adjusting the `define user` forms in the [Colang files](../user_guides/colang-language-syntax-guide.md), or modifying the sample conversations in the [configuration](../user_guides/configuration-guide.md).
 3. Nondeterminism: LLMs use a concept known as *temperature*, as well as other techniques, to introduce variation in their responses. This creates a much more natural experience, however, it can on occasion create unexpected behavior in LLM applications that can be difficult to reproduce. As with all AI applications, it is a good practice to use thorough evaluation and regression-testing suites.
 

diff --git a/docs/security/index.rst b/docs/security/index.rst
@@ -0,0 +1,10 @@
+:orphan:
+
+Security
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   guidelines
+   red-teaming
diff --git a/docs/security/red-teaming.md b/docs/security/red-teaming.md
@@ -12,7 +12,7 @@ To run a red teaming process, there are three steps involved:
 2. Create a set of challenges (`challenges.json`) and add them to the `config` folder.
 3. Start the server `nemoguardrails server` and use the Chat UI to interact with various configurations.
 
-For a server configuration template with two guardrails configuration and a set of challenges, check out [this example](../../examples/configs/red-teaming).
+For a server configuration template with two guardrails configuration and a set of challenges, check out [this example](../../examples/configs/red-teaming/README.md).
 
 ## Challenges
 
@@ -54,4 +54,4 @@ The UI enables the user to rate the attack's success (No Success, Some Success,
 
 ## Recording the results
 
-The sample configuration [here](../../examples/configs/red-teaming) includes an example of how to use a "custom logger" to save the ratings, including the complete history of the conversation, in a CSV file.
+The sample configuration [here](../../examples/configs/red-teaming/README.md) includes an example of how to use a "custom logger" to save the ratings, including the complete history of the conversation, in a CSV file.
diff --git a/docs/user_guides/advanced/align-score-deployment.md b/docs/user_guides/advanced/align-score-deployment.md
@@ -1,6 +1,6 @@
 # AlignScore Deployment
 
-**NOTE**: The recommended way to use AlignScore with NeMo Guardrails is using the provided [Dockerfile](../../../nemoguardrails/library/factchecking/align_score/Dockerfile). For more details, check out how to [build and use the image](./using-docker.md).
+**NOTE**: The recommended way to use AlignScore with NeMo Guardrails is using the provided [Dockerfile](https://github.com/NVIDIA/NeMo-Guardrails/blob/develop/nemoguardrails/library/factchecking/align_score/Dockerfile). For more details, check out how to [build and use the image](using-docker.md).
 
 In order to deploy an AlignScore server, follow these steps:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -53,4 +53,4 @@ At the same time, this experiment does not investigate if the guardrails also bl

		## LLM Vulnerability Categories

		If you are interested in additional information about each vulnerability category in Garak, please consult the full results [here](./../_static/html/) and the [Garak GitHub](https://github.com/leondz/garak/) page.
		If you are interested in additional information about each vulnerability category in Garak, please consult the full results [here](./../_static/html/README.md) and the [Garak GitHub](https://github.com/leondz/garak/) page.