docs: Publishing Requirements

.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.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.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
+```
+
+