Implement Sphinx documentation #48

ahnaf-tahmid-chowdhury · 2025-06-01T17:21:06Z

Description

This PR introduces a comprehensive documentation setup for PyDAGMC using Sphinx.

Key changes:

Configured Sphinx with Myst-parser for Markdown support and sphinx-book-theme.
Added necessary documentation dependencies (sphinx, sphinx-book-theme, myst-parser, nbsphinx, etc.) to pyproject.toml.
Created initial page structure:
- User Guide
- Tutorial
- Methodology
- API Reference (autodoc for pydagmc.dagnav)
- Getting Help
Updated README.md to reflect new documentation and add a link.
Configured conf.py for theme, extensions, and autodoc settings.

Live demo: https://ahnaf-tahmid-chowdhury.github.io/pydagmc/

codecov · 2025-06-01T17:22:43Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@1af3754). Learn more about missing BASE report.
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #48   +/-   ##
=======================================
  Coverage        ?   97.19%           
=======================================
  Files           ?        2           
  Lines           ?      428           
  Branches        ?       47           
=======================================
  Hits            ?      416           
  Misses          ?        9           
  Partials        ?        3

Flag	Coverage Δ
unittests	`97.19% <ø> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

pshriwise

Initial review here. Overall, I think this looks quite good. It's much appreciated @ahnaf-tahmid-chowdhury!

docs/source/user-guide.md

docs/source/methodology.md

pshriwise · 2025-07-03T17:09:34Z

docs/source/methodology.md

+
+At the core, DAGMC geometry is organized using MOAB **Entity Sets**. These are collections of other entities, which can include mesh elements (like triangles) or other entity sets, forming a hierarchical structure. PyDAGMC maps these entity sets to its `Group`, `Volume`, and `Surface` classes.
+
+### Essential MOAB Tags Used by DAGMC


Haven't fully parsed it yet, but I do like this summary. I think it would be better placed in a section on the DAGMC file data model rather than methodology.

created new file called data-model and moved the contents there

I don't see that file in this PR?

Recently merged it back into the methodology file with a dedicated section.

pshriwise · 2025-07-03T17:10:57Z

docs/source/methodology.md

+* **Volumes and Surfaces:** A `Volume` entity set typically contains `Surface` entity sets that form its boundary. PyDAGMC uses `mb.get_child_meshsets(volume_handle)` to find a `Volume`'s surfaces and `mb.get_parent_meshsets(surface_handle)` to find a `Surface`'s parent volumes.
+* **Groups and Volumes/Surfaces:** A `Group` entity set contains `Volume` and/or `Surface` entity sets. PyDAGMC uses `mb.get_entities_by_type_and_tag` within the group's handle to find its constituent volumes and surfaces.
+
+## PyDAGMC Class Structure


In contrast to the "EntitySets", " Essemtial MOAB Tags...", and "Implicit Relationships...", sections above, the content in this section seems appropriate for methodology. Let's relocate the other sections.

CONTRIBUTING.md

SECURITY.md

docs/source/getting-help.md

docs/source/index.md

pshriwise · 2025-07-05T17:30:23Z

docs/source/methodology.md

+  * Then, the specific class (e.g., `Volume`) is instantiated with this configured handle.
+  * An ID is assigned, either user-provided or auto-generated to be unique within the model for that entity type.
+
+* **Volume Calculation (`Volume.volume`):**


Note to myself to review the rendered version of this equation.

Co-authored-by: Patrick Shriwise <pshriwise@gmail.com>

The 'EntitySets', 'Essential MOAB Tags', and 'Implicit Relationships' sections were moved from the methodology page to a new data-model page to improve the documentation's structure. A link to the new page has been added to the table of contents.

…ture - Updated the title and introductory text in the tutorial to enhance engagement and clarity. - Improved the organization of the tutorial sections, emphasizing key functionalities of PyDAGMC. - Added a new section in the tutorial detailing the internal operations of PyDAGMC, providing insights into model loading, entity access, triangle data handling, material assignment, entity creation, and volume calculation.

ahnaf-tahmid-chowdhury · 2025-08-10T15:44:28Z

@pshriwise I think you are suggesting removing the PyDAGMC Class Structure section from the methodology and keeping DAGMC Data Model there. If that’s correct, please let me know and I’ll update it accordingly.

pshriwise · 2025-08-31T17:16:02Z

docs/source/methodology.md

+    F ==> G["Build Implicit Relationships"]
+    G ==> H["Enable Queries"]
+    H ==> I["Extract Geometry"]


A lot of this is done as part of MOAB. I don't think it's important to break down a file load in this kind of detail here. Mainly what users will be interested in (in my opinion) is what they can do with a file once loaded. In short, an additional sentence above to capture all of this should suffice. something like:

"When a file is loaded, its embedded geometric topology relationships and metadata (material/property assignments) are loaded according to the conventions established by the DAGMC library."

gonuke

I made a few suggestions here, but it looks like we're waiting on responses to other review comments still.

CONTRIBUTING.md

gonuke · 2025-09-18T12:00:09Z

README.md


 PyDAGMC is a Python interface for interacting with DAGMC .h5m files through the embedded topological relationships and metadata contained within. These interactions occur through a set of Python classes corresponding to DAGMC’s metadata Group (a grouping of volumes or surfaces), Volume, and Surface groupings in the mesh database. This interface is intended to provide a simple interface for obtaining information about DAGMC models, replacing significant boilerplate code required to perform the same queries with PyMOAB, the Python interface for MOAB itself.

-PyDAGMC classes provide the ability to perform basic queries as properties of the class instances. These queries include:


I think many users like to see some basic documentation like this in the README on GH so they don't have to dive into a complete documentation page. I think it would be good to leave this here, but move the link to detailed documentation before this.

gonuke · 2025-09-18T12:02:00Z

docs/source/conf.py

+
+project = 'PyDAGMC'
+copyright = '2023 - {}, The UW CNERG Team. All rights reserved'.format(datetime.date.today().year)
+author = 'Patrick Shriwise, Paul Wilson, et al'


There are other authors who deserve more recognition than me (e.g. Romano, Peterson). We should either be comprehensive or find another way to list authors here.

gonuke · 2025-09-18T12:04:43Z

pyproject.toml

+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",


Should we get rid of some of these old versions?

gonuke · 2025-09-18T12:06:02Z

docs/source/index.md

@@ -0,0 +1,52 @@
+# Welcome to PyDAGMC
+
+PyDAGMC is a Python interface for interacting with DAGMC `.h5m` files


Can we link the word "DAGMC" to the DAGMC documentation (such as it is) here and throughout?

gonuke · 2025-09-18T12:11:02Z

docs/source/methodology.md

+
+# Methodology
+
+PyDAGMC provides a Pythonic abstraction layer over PyMOAB for interacting with DAGMC (Direct Accelerated Geometry Monte Carlo) `.h5m` files. This section delves into the underlying concepts, data structures, and design choices that enable PyDAGMC's functionality.


I wonder if we should include a statement about what a DAGMC file actually is? Something like:

A DAGMC file contains a surface mesh representation of a geometry, including metadata to define the topological relationships of that geometry and material assignments, using MOAB's mesh file conventions. The metadata conventions are specific to DAGMC.

We do get into it more in the details below, but perhaps some early statement like this is helpful context and provides some useful vocabulary and semantic nuance.

gonuke · 2025-09-18T12:14:33Z

docs/source/methodology.md

+
+At the core, DAGMC geometry is organized using MOAB **Entity Sets**. These are collections of other entities, which can include mesh elements (like triangles) or other entity sets, forming a hierarchical structure. PyDAGMC maps these entity sets to its `Group`, `Volume`, and `Surface` classes.
+
+### Essential MOAB Tags Used by DAGMC


I don't see that file in this PR?

Co-authored-by: Paul Wilson <paul.wilson@wisc.edu>

ahnaf-tahmid-chowdhury added 30 commits May 31, 2025 23:41

add docs

a711a4d

add documentation link

374d3e4

sphinx quickstart

97f8826

nbsphinx_execute always

5eecb2a

add ipykernel

0c548e1

add security file

6653992

add dagmc logo

d330a9a

add code of conduct

fbb4388

contact Paul Wilson

5a4eaf5

add contributing

8095903

add security file

d3b9ffb

remove dev comments

9ebe750

add sphinxcontrib-mermaid

729e077

add welcome page

f52a63a

add user guide

951833f

add templates

b81aa09

include root level files to doc

ca4b9ca

add getting help

2136e95

add api

7a1a94d

add tutorial

51a4af0

Clean up downloaded and created files

c49d0cd

add methodology

0774667

better format

8f15841

add readthedocs

8c56e40

add docs workflow

12aebc7

add pandoc

4d4b243

conda use base

a05e69c

python -m pip install .[docs]

fdf2ad3

conda run -n base pip install .[docs]

8ea1822

add conda run

80c77c6

ahnaf-tahmid-chowdhury added 2 commits June 1, 2025 22:57

remove html folder

e18c2b8

reduce title size

a138eec

ahnaf-tahmid-chowdhury added 3 commits June 1, 2025 23:29

better markdown format

b98878b

NukeBox -> PyDAGMC

902733c

remove extra .

e667b43

pshriwise requested changes Jul 5, 2025

View reviewed changes

ahnaf-tahmid-chowdhury and others added 7 commits August 3, 2025 23:23

Update docs/source/methodology.md

02c6e28

Co-authored-by: Patrick Shriwise <pshriwise@gmail.com>

Update CONTRIBUTING.md

9697da1

Co-authored-by: Patrick Shriwise <pshriwise@gmail.com>

Update docs/source/getting-help.md

e341a39

Co-authored-by: Patrick Shriwise <pshriwise@gmail.com>

Update docs/source/index.md

2dcd55b

Co-authored-by: Patrick Shriwise <pshriwise@gmail.com>

chore: remove unused sections from issue and pull request templates

5df61d4

ahnaf-tahmid-chowdhury requested a review from pshriwise August 3, 2025 18:43

ahnaf-tahmid-chowdhury mentioned this pull request Aug 29, 2025

Add example of renaming group #51

Open

pshriwise reviewed Aug 31, 2025

View reviewed changes

ahnaf-tahmid-chowdhury added 3 commits September 18, 2025 09:32

remove security

87b563f

update methodology

c22a2a7

Merge remote-tracking branch 'upstream/main' into doc

0c7faf4

gonuke requested changes Sep 18, 2025

View reviewed changes

ahnaf-tahmid-chowdhury and others added 5 commits September 18, 2025 18:43

Update CONTRIBUTING.md

526a778

Co-authored-by: Paul Wilson <paul.wilson@wisc.edu>

restore previous intro

9224137

short the title

7359c48

update python

49b29a8

apply @gonuke's suggestions

2578db4


		At the core, DAGMC geometry is organized using MOAB Entity Sets. These are collections of other entities, which can include mesh elements (like triangles) or other entity sets, forming a hierarchical structure. PyDAGMC maps these entity sets to its `Group`, `Volume`, and `Surface` classes.

		### Essential MOAB Tags Used by DAGMC


		PyDAGMC is a Python interface for interacting with DAGMC .h5m files through the embedded topological relationships and metadata contained within. These interactions occur through a set of Python classes corresponding to DAGMC’s metadata Group (a grouping of volumes or surfaces), Volume, and Surface groupings in the mesh database. This interface is intended to provide a simple interface for obtaining information about DAGMC models, replacing significant boilerplate code required to perform the same queries with PyMOAB, the Python interface for MOAB itself.

		PyDAGMC classes provide the ability to perform basic queries as properties of the class instances. These queries include:

		@@ -0,0 +1,52 @@
		# Welcome to PyDAGMC

		PyDAGMC is a Python interface for interacting with DAGMC `.h5m` files


		# Methodology

		PyDAGMC provides a Pythonic abstraction layer over PyMOAB for interacting with DAGMC (Direct Accelerated Geometry Monte Carlo) `.h5m` files. This section delves into the underlying concepts, data structures, and design choices that enable PyDAGMC's functionality.

Implement Sphinx documentation #48

Are you sure you want to change the base?

Implement Sphinx documentation #48

Conversation

ahnaf-tahmid-chowdhury commented Jun 1, 2025

Description

Key changes:

Uh oh!

codecov bot commented Jun 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pshriwise left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pshriwise Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ahnaf-tahmid-chowdhury commented Aug 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gonuke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codecov bot commented Jun 1, 2025 •

edited

Loading

pshriwise Jul 5, 2025 •

edited

Loading