Miscellaneous fixes including moving / removing "contributing" sectio…

…n from the web docs (#428)
NVIDIA · Feb 12, 2025 · 74c21fe · 74c21fe
1 parent 29563dd
commit 74c21fe
Show file tree

Hide file tree

Showing 16 changed files with 76 additions and 255 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -38,8 +38,9 @@ External contributions will be welcome soon, and they are greatly appreciated! E
    - [Principle of Least Knowledge (Law of Demeter)](#11-principle-of-least-knowledge-law-of-demeter)
    - [Document Assumptions and Decisions](#12-document-assumptions-and-decisions)
    - [Continuous Integration and Testing](#13-continuous-integration-and-testing)
-5. [Licensing](#licensing)
-6. [Attribution](#attribution)
+5. [Writing Good and Thorough Documentation](#writing-good-and-thorough-documentation)
+6. [Licensing](#licensing)
+7. [Attribution](#attribution)
 
 ## Filing Issues
 
@@ -417,6 +418,61 @@ followed:
 Contributors are encouraged to follow these guidelines to ensure contributions are in line with the project's
 architectural consistency and maintainability.
 
+
+## Writing Good and Thorough Documentation
+
+As a contributor to our codebase, writing high-quality documentation is an essential part of ensuring that others can
+understand and work with your code effectively. Good documentation helps to reduce confusion, facilitate collaboration,
+and streamline the development process. In this guide, we will outline the principles and best practices for writing
+thorough and readable documentation that adheres to the Chicago Manual of Style.
+
+### Chicago Manual of Style
+
+Our documentation follows the Chicago Manual of Style, a widely accepted standard for writing and formatting. This style
+guide provides a consistent approach to writing, grammar, and punctuation, making it easier for readers to understand
+and navigate our documentation.
+
+### Key Principles
+
+When writing documentation, keep the following principles in mind:
+
+1. **Clarity**: Use clear and concise language to convey your message. Avoid ambiguity and jargon that may confuse readers.
+2. **Accuracy**: Ensure that your documentation is accurate and up-to-date. Verify facts, details, and code snippets
+    before publishing.
+3. **Completeness**: Provide all necessary information to understand the code, including context, syntax, and examples.
+4. **Consistency**: Use a consistent tone, voice, and style throughout the documentation.
+5. **Accessibility**: Make your documentation easy to read and understand by using headings, bullet points, and short paragraphs.
+
+### Documentation Structure
+
+A well-structured documentation page should include the following elements:
+
+1. **Header**: A brief title that summarizes the content of the page.
+2. **Introduction**: A short overview of the topic, including its purpose and relevance.
+3. **Syntax and Parameters**: A detailed explanation of the code syntax, including parameters, data types, and return values.
+4. **Examples**: Concrete examples that illustrate how to use the code, including input and output.
+5. **Tips and Variations**: Additional information, such as best practices, common pitfalls, and alternative approaches.
+6. **Related Resources**: Links to relevant documentation, tutorials, and external resources.
+
+### Best Practices
+
+To ensure high-quality documentation, follow these best practices:
+
+1. **Use headings and subheadings**: Organize your content with clear headings and subheadings to facilitate scanning and navigation.
+2. **Use bullet points and lists**: Break up complex information into easy-to-read lists and bullet points.
+3. **Provide context**: Give readers a clear understanding of the code's purpose, history, and relationships to other components.
+4. **Review and edit**: Carefully review and edit your documentation to ensure accuracy, completeness, and consistency.
+
+### Resources
+
+For more information on the Chicago Manual of Style, refer to their
+[online published version](https://www.chicagomanualofstyle.org/home.html?_ga=2.188145128.1312333204.1728079521-706076405.1727890116).
+
+By following these guidelines and principles, you will be able to create high-quality documentation that helps others
+understand and work with your code effectively. Remember to always prioritize clarity, accuracy, and completeness, and
+to use the Chicago Style Guide as your reference for writing and formatting.
+
+
 ## Licensing
 
 NV-Ingest is licensed under the NVIDIA Proprietary Software License -- ensure that any contributions are compatible.

diff --git a/README.md b/README.md
@@ -274,7 +274,7 @@ result = client.fetch_job_result(job_id, timeout=60)
 print(f"Got {len(result)} results")
 ```
 
-#### Using the the `nv-ingest-cli`
+#### Using the `nv-ingest-cli`
 
 > [!NOTE]
 > You can find more examples [here](client/client_examples/examples/).

diff --git a/client/client_examples/examples/python_client_usage.ipynb b/client/client_examples/examples/python_client_usage.ipynb
@@ -10,7 +10,7 @@
     "This notebook provides a quick start guide to using the NV-Ingest Python API to create a client that interacts with a running NV-Ingest cluster. It will walk through the following:\n",
     "\n",
     "- Define the task configuration for an NV-Ingest job\n",
-    "- Submit a job the the NV-Ingest cluster and retrieve completed results\n",
+    "- Submit a job to the NV-Ingest cluster and retrieve completed results\n",
     "- Investigate the multimodal extractions"
    ]
   },

diff --git a/docs/docs/user-guide/SUMMARY.md b/docs/docs/user-guide/SUMMARY.md
@@ -1,5 +1,6 @@
 - [What is NVIDIA Ingest?](index.md)
-- [Getting Started](getting-started/)
+- [Prerequisites](prerequisites.md)
+- [Quickstart](quickstart-guide.md)
 - [Developer Guide](developer-guide/)
-- [Contributing](contributing/)
-- [Appendix](appendix/)
+- [Contributing](contributing.md)
+- [Release Notes](releasenotes-nv-ingest.md)
diff --git a/docs/docs/user-guide/contributing.md b/docs/docs/user-guide/contributing.md
@@ -0,0 +1,4 @@
+# Contributing to NVIDIA-Ingest
+
+External contributions to NVIDIA-Ingest will be welcome soon, and they are greatly appreciated! 
+For more information, refer to [Contributing to NVIDIA-Ingest](https://github.com/NVIDIA/nv-ingest/blob/main/CONTRIBUTING.md).
diff --git a/docs/docs/user-guide/contributing/Writing Documentation/index.md b/docs/docs/user-guide/contributing/Writing Documentation/index.md
diff --git a/docs/docs/user-guide/contributing/Writing Documentation/jupyter-notebooks.ipynb b/docs/docs/user-guide/contributing/Writing Documentation/jupyter-notebooks.ipynb
diff --git a/docs/docs/user-guide/contributing/Writing Documentation/mkdocs.md b/docs/docs/user-guide/contributing/Writing Documentation/mkdocs.md
diff --git a/docs/docs/user-guide/contributing/code-review.md b/docs/docs/user-guide/contributing/code-review.md
diff --git a/docs/docs/user-guide/contributing/contributing.md b/docs/docs/user-guide/contributing/contributing.md
diff --git a/docs/docs/user-guide/getting-started/SUMMARY.md b/docs/docs/user-guide/getting-started/SUMMARY.md
diff --git a/...er-guide/getting-started/prerequisites.md → docs/docs/user-guide/prerequisites.md b/...er-guide/getting-started/prerequisites.md → docs/docs/user-guide/prerequisites.md
diff --git a/...guide/getting-started/quickstart-guide.md → docs/docs/user-guide/quickstart-guide.md b/...guide/getting-started/quickstart-guide.md → docs/docs/user-guide/quickstart-guide.md
@@ -13,14 +13,14 @@ This example demonstrates how to use the provided [docker-compose.yaml](https://
 
 **IMPORTANT:** NIM containers on their first startup can take 10-15 minutes to pull and fully load models.
 
-If preferred, you can also [start services one by one](../../user-guide/developer-guide/deployment.md) or run on Kubernetes via [our Helm chart](https://github.com/NVIDIA/nv-ingest/blob/main/helm/README.md). Also, there are [additional environment variables](../../user-guide/developer-guide/environment-config.md) you want to configure.
+If preferred, you can also [start services one by one](developer-guide/deployment.md) or run on Kubernetes via [our Helm chart](https://github.com/NVIDIA/nv-ingest/blob/main/helm/README.md). Also, there are [additional environment variables](developer-guide/environment-config.md) you want to configure.
 
 1. Git clone the repo:
 `git clone https://github.com/nvidia/nv-ingest`
 2. Change the directory to the cloned repo
 `cd nv-ingest`.
 
-3. [Generate API keys](../../user-guide/developer-guide/ngc-api-key.md) and authenticate with NGC with the `docker login` command:
+3. [Generate API keys](developer-guide/ngc-api-key.md) and authenticate with NGC with the `docker login` command:
 ```shell
 # This is required to access pre-built containers and NIM microservices
 $ docker login nvcr.io
@@ -29,11 +29,11 @@ Password: <Your Key>
 ```
 
 > [!NOTE]
-> During the early access (EA) phase, you must apply for early access here: https://developer.nvidia.com/nemo-microservices-early-access/join. 
+> During the early access (EA) phase, you must apply for early access at [https://developer.nvidia.com/nemo-microservices-early-access/join](https://developer.nvidia.com/nemo-microservices-early-access/join). 
 > When your early access is approved, follow the instructions in the email to create an organization and team, link your profile, and generate your NGC API key.
 
 
-4. Create a .env file containing your NGC API key and the following paths. For more information, refer to [Environment Configuration Variables](../developer-guide/environment-config.md).
+4. Create a .env file containing your NGC API key and the following paths. For more information, refer to [Environment Configuration Variables](developer-guide/environment-config.md).
 
 ```
 # Container images must access resources from NGC.
@@ -57,7 +57,7 @@ NV_INGEST_ROOT=<PATH_TO_THIS_REPO>
 5. Start all services:
 `docker compose up`
 
-> **TIP:** By default, we have [configured log levels to be verbose]([docker-compose.yaml](https://github.com/NVIDIA/nv-ingest/blob/main/docker-compose.yaml#L27).
+> **TIP:** By default, we have [configured log levels to be verbose](docker-compose.yaml).
 >
 > It's possible to observe service startup proceeding. You will notice a lot of log messages. Disable verbose logging by configuring `NIM_TRITON_LOG_VERBOSE=0` for each NIM in [docker-compose.yaml](https://github.com/NVIDIA/nv-ingest/blob/main/docker-compose.yaml).
 
@@ -261,7 +261,7 @@ multimodal_test.pdf.metadata.json
 processed_docs/text:
 multimodal_test.pdf.metadata.json
 ```
-You can view the full JSON extracts and the metadata definitions [here](../../user-guide/developer-guide/content-metadata.md). We also provide a script for inspecting [extracted images](https://github.com/NVIDIA/nv-ingest/blob/main/src/util/image_viewer.py).
+You can view the full JSON extracts and the metadata definitions [here](developer-guide/content-metadata.md). We also provide a script for inspecting [extracted images](https://github.com/NVIDIA/nv-ingest/blob/main/src/util/image_viewer.py).
 
 First, install `tkinter` by running the following commands depending on your OS.
 - For Ubuntu/Debian Linux:

diff --git a/...-guide/appendix/releasenotes-nv-ingest.md → ...docs/user-guide/releasenotes-nv-ingest.md b/...-guide/appendix/releasenotes-nv-ingest.md → ...docs/user-guide/releasenotes-nv-ingest.md
diff --git a/examples/store_and_display_images.ipynb b/examples/store_and_display_images.ipynb
@@ -435,7 +435,7 @@
    "id": "4051d5ad-b754-4f4f-92ff-7d9175229c6f",
    "metadata": {},
    "source": [
-    "Now, we have a listt of results containing our extracted images, charts, and tables encoded in base64. We can display one of the the base64 encoded images above by converting it into a BytesIO object and displying it with PIL"
+    "Now, we have a listt of results containing our extracted images, charts, and tables encoded in base64. We can display one of the base64-encoded images above by converting it into a BytesIO object and displying it with PIL"
    ]
   },
   {

diff --git a/helm/README.md b/helm/README.md
@@ -36,7 +36,7 @@ helm repo add nvidia-nim https://helm.ngc.nvidia.com/nim/nvidia --username='$oau
 helm upgrade \
     --install \
     nv-ingest \
-    https://helm.ngc.nvidia.com/nvidia/nemo-microservices/charts/nv-ingest-0.4.0.tgz
+    https://helm.ngc.nvidia.com/nvidia/nemo-microservices/charts/nv-ingest-0.4.0.tgz \
     -n ${NAMESPACE} \
     --username '$oauthtoken' \
     --password "${NGC_API_KEY}" \