Merge pull request #69 from SteSeg/restore_doc3

Documentation update

Author: SteSeg

docs/source/conf.py

@@ -15,6 +15,9 @@
     'sphinxcontrib.bibtex',
 ]
 
+# The master document (entry point)
+master_doc = 'index'
+
 # Bibliography files
 bibtex_bibfiles = ['references.bib']
 bibtex_reference_style = 'label'
@@ -24,7 +27,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '_config.yml', '_toc.yml']
 
 # -- Options for HTML output -------------------------------------------------
 html_theme = 'sphinx_book_theme'
@@ -44,8 +47,14 @@
     'colon_fence',
     'deflist',
     'dollarmath',
+    'html_image',
 ]
 
+# Allow HTML in Markdown
+myst_html_meta = {
+    "description lang=en": "OpenMC Fusion Benchmarks documentation",
+}
+
 # Don't execute notebooks (set to 'off' to disable)
 # This is equivalent to jupyter-book's execute_notebooks: false
 jupyter_execute_notebooks = 'off'

docs/source/index.md

@@ -0,0 +1,14 @@
+# OpenMC Fusion Benchmarks
+
+Welcome to the **OpenMC Fusion Benchmarks** project - a modular, code-agnostic, and automation-ready repository for defining, executing, and analyzing radiation transport benchmarks in fusion energy systems. Benchmarks are described through a rigorous, schema-driven YAML specification, and include detailed **CAD-based geometries** with automatic meshing support. The framework is designed for **easy integration and testing of new neutronics methods**, facilitating rapid development, comparison, and validation across codes, workflows, and datasets.
+
+## Contents
+
+```{toctree}
+:maxdepth: 2
+
+intro
+user_installation
+oktavian_readme
+oktavian_al_benchmark
+```

docs/source/index.rst

@@ -1,6 +1,44 @@
-# Welcome OpenMC Fusion Benchmarks
+# Introduction
 
-OpenMC Fusion Benchmarks is a platform for V&V of fusion neutronics. It focuses on fusion-relevant integral benchmarks. It relies on an automated workflow for model simulation, data postprocessing, visualization and analysis. It embeds a database of experimental and numerical results for quick comparisons to which users can contribute to. The database contribution workflow is fully automated.
+**OpenMC Fusion Benchmarks** builds on a modular and schema-driven approach to radiation transport benchmarking, with a focus on reproducibility, extensibility, and automation. Each benchmark is fully defined by a standardized `specifications.yaml` file, which captures all aspects of the model — including CAD-based geometry, materials, source definitions, simulation parameters, and reference results.
 
-```{tableofcontents}
-```
+This approach enables consistent validation, execution, and postprocessing of benchmarks across tools and workflows. The repository is also designed to facilitate the implementation and testing of new neutronics methods in a code-agnostic environment.
+
+---
+
+## Key Features
+
+- **Standardized benchmark definitions** via `specifications.yaml`
+- **Validation** of `specifications.yaml` against a strict `benchmark_schema.yaml`
+- **CAD-based geometries** and automatic meshing tools
+- **Automated workflow** for benchmark building, running and analysis through Python APIs
+- **Unified results format** for comparing experimental, historical, and simulated data
+- **Embedded Uncertainty Quantification** for _best estimate plus uncertainty_ approach
+- **Benchmark and results libraries** with descriptions, `specifications` and results
+
+---
+
+## Get Started
+
+- [Quickstart Guide](quickstart.md)
+- [Benchmark Specifications Format](specifications/overview.md)
+- [Available Benchmarks](benchmark_collection/index.md)
+- [Workflows: from definition to analysis]()
+- [Python API]()
+- [Example Notebooks]()
+
+---
+
+## How to Contribute
+
+We welcome contributions of new benchmarks, improvements to the schema, and extensions to the tools and analysis pipelines. See our [Contributing Guidelines](https://github.com/your-org/your-repo/blob/main/CONTRIBUTING.md) for more.
+
+For questions, ideas, or bug reports, please open an [issue](https://github.com/eepeterson/openmc_fusion_benchmarks/issues) or reach out to the maintainers.
+
+---
+
+## License and Citation
+
+This project is open source under the [MIT License](https://github.com/eepeterson/openmc_fusion_benchmarks/blob/develop/LICENSE).
+
+If you use this benchmark format or collection in your work, please cite: