docs: Publishing Requirements (#17)

* First pass of fixes

Signed-off-by: Andrew Schilling <aschilling@nvidia.com>

* Markdown generation

Signed-off-by: Andrew Schilling <aschilling@nvidia.com>

* Adding overview

Signed-off-by: Andrew Schilling <aschilling@nvidia.com>

* API Cleanup

Signed-off-by: Andrew Schilling <aschilling@nvidia.com>

* Name corrections

Signed-off-by: Andrew Schilling <aschilling@nvidia.com>

* pre-commit

Signed-off-by: Andrew Schilling <aschilling@nvidia.com>

* adjusting .gitignore

Signed-off-by: Andrew Schilling <aschilling@nvidia.com>

---------

Signed-off-by: Andrew Schilling <aschilling@nvidia.com>

Author: aschilling-nv

.gitignore

@@ -88,7 +88,6 @@ instance/
 
 # Sphinx documentation
 docs/_build
-docs/apidocs
 
 # PyBuilder
 target/

docs/apidocs/index.md

@@ -0,0 +1,11 @@
+# API Reference
+
+NeMo Emerging Optimizers API reference provides comprehensive technical documentation for all modules, classes, and functions.
+
+```{toctree}
+:caption: API Documentation
+:hidden:
+
+utils.md
+orthogonalized-optimizers.md
+```

docs/orthogonalized_optimizers.rst docs/apidocs/orthogonalized-optimizers.mddocs/orthogonalized_optimizers.rst renamed to docs/apidocs/orthogonalized-optimizers.md

@@ -1,3 +1,4 @@
+```{eval-rst}  
 .. role:: hidden
     :class: hidden-section
 
@@ -28,3 +29,4 @@ emerging_optimizers.orthogonalized_optimizers
 .. autofunction:: newton_schulz
 .. autofunction:: newton_schulz_step
 .. autofunction:: newton_schulz_tp
+```

docs/utils.rst docs/apidocs/utils.mddocs/utils.rst renamed to docs/apidocs/utils.md

@@ -1,3 +1,5 @@
+
+```{eval-rst}  
 .. role:: hidden
     :class: hidden-section
 
@@ -21,3 +23,4 @@ emerging_optimizers.utils
 ~~~~~~~~~~~~~~~~~~~~~
 
 .. autofunction:: get_pg_rank
+```

docs/conf.py

@@ -27,7 +27,7 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "Emerging Optimizers"
+project = "Emerging-Optimizers"
 copyright = "2025, NVIDIA Corporation"
 author = "NVIDIA Corporation"
 release = "0.1.0"
@@ -36,6 +36,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+    "myst_parser",  # For our markdown docs
     "sphinx.ext.viewcode",  # For adding a link to view source code in docs
     "sphinx.ext.doctest",  # Allows testing in docstrings
     "sphinx.ext.napoleon",  # For google style docstrings
@@ -47,7 +48,6 @@
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
     "sphinx.ext.autosectionlabel",
-    "sphinx_panels",
     "sphinx.ext.linkcode",
 ]
 
@@ -61,7 +61,10 @@
 katex_prerender = False
 napoleon_use_ivar = True
 html_domain_indices = False
-source_suffix = ".rst"
+source_suffix = {
+    ".md": "markdown",
+    ".rst": "restructuredtext",
+}
 master_doc = "index"
 autodoc_docstring_signature = True
 intersphinx_mapping = {
@@ -93,6 +96,13 @@ def linkcode_resolve(domain, info):
 
 html_theme = "nvidia_sphinx_theme"
 html_theme_options = {
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/NVIDIA-NeMo/Emerging-Optimizers/",
+            "icon": "fa-brands fa-github",
+        }
+    ],
     "switcher": {
         "json_url": "../versions1.json",
         "version_match": release,
@@ -109,7 +119,6 @@ def linkcode_resolve(domain, info):
     },
 }
 html_extra_path = ["project.json", "versions1.json"]
-
 # Github links are now getting rate limited from the Github Actions
 linkcheck_ignore = [
     ".*github\\.com.*",

docs/index.md

@@ -0,0 +1,40 @@
+# Emerging Optimizers Documentation
+
+## Overview
+
+Emerging Optimizers is a research project focused on understanding and optimizing the algorithmic behavior of Shampoo class optimizers (Shampoo, SOAP, Muon, etc.) and their implications to performance of GPU systems in LLM training.
+
+:::{note}
+Emerging-Optimizers is under active development. All APIs are experimental and subject to change. New features, improvements, and documentation updates are released regularly. Your feedback and contributions are welcome, and we encourage you to follow along as new updates roll out.
+:::
+
+## Installation
+
+### Prerequisites
+
+- Python 3.12 or higher
+- PyTorch 2.0 or higher
+
+### Install from Source
+
+```bash
+git clone https://github.com/NVIDIA-NeMo/Emerging-Optimizers.git
+cd Emerging-Optimizers
+pip install .
+```
+
+## User guide
+
+Coming soon.
+
+
+
+```{toctree}
+:caption: 🛠️ Development
+:hidden:
+
+documentation.md
+apidocs/index.md
+```
+
+