search

idaholab / MontePy

MontePy is the most user friendly Python library (API) to read, edit, and write MCNP input files.
https://www.montepy.org/
MIT License
30 stars 6 forks source link

Add references to MCNP Manual in docstrings for Input classes #413

Open tjlaboss opened 3 months ago

tjlaboss commented 3 months ago

Is your feature request related to a problem? Please describe. No

Describe the solution you'd like For each publicly-available users manuals for versions of MCNP supported by MontePy, add a reference to the corresponding section of the user's manual where the input syntax is described. Right now, this is: MCNP4C, MCNPX, MCNP6.2, MCNP6.3

Describe alternatives you've considered

Additional context A good first issue for a new developer to become familiar with MontePy data types and MCNP syntax.

MicahGale commented 3 months ago

So 1. I didn't know about MCNP4C and MCNPX being publicly available.

As of right now we do support 6.2 and 6.3 exclusively officially.

The 6.3 manual was moved all about so the section numbers are different. I want to add the 6.3 manual for sure. I'm not sure how I feel about 6.2.

Some food for thought:

  1. Can we reliably hyperlink to a specific section in any of the manuals? I feel like this should be possible.
  2. Should we make a sphinx extension to automate this. 
.. mcnp:
   6.2: 5.1.2.3
   6.3: 1.2.3.4

This could then be rendered as:

Further reading: MCNP Version Section
6.2 5.1.2.3
6.3 1.2.3.4
tjlaboss commented 3 months ago

Supporting only the latest would be cleanest. It would be the same amount of work to maintain this for only the latest release or all supported releases starting at 6.2.

Hyperlinking: I don't know how reliable this is, but you could do it. Here is an example based on a section I was just looking at.

Obviously, the PDF link should be a variable so that it can be readily updated if the LANL website moves the PDFs again.

MicahGale commented 3 months ago

Obviously, the PDF link should be a variable so that it can be readily updated ~if~ when the LANL website moves the PDFs again.

FTFY

MicahGale commented 3 months ago

I feel like we should split this into two tasks: build the machinery, and then populate the fields. I don't think building the machinery in sphinx would be necessarily a good first issue.

MicahGale commented 3 months ago

I'm wondering if there's an existing sphinx package that could be hacked to do this.

tjlaboss commented 3 months ago

https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html

MicahGale commented 3 months ago

Yes! We can also use that to link to issues from the changelog, etc!

tjlaboss commented 3 months ago

I feel like we should split this into two tasks: build the machinery, and then populate the fields. I don't think building the machinery in sphinx would be necessarily a good first issue.

The machinery is pretty easy, but then again, I'm the official unofficial Sphinx documentation guy. I just implemented it for MCNP6.3.