Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
tjlaboss opened this issue Jun 17, 2024 · 9 comments
Open

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

tjlaboss opened this issue Jun 17, 2024 · 9 comments
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers

Comments

@tjlaboss
Copy link
Collaborator

tjlaboss commented Jun 17, 2024

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

  • Only reference the latest (right now, MCNP6.3, specifically Chapter 5). This should work as the MCNP team strives to maintain backward compatibility.
  • Only reference manuals ≥MCNP6.2

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

@tjlaboss tjlaboss added documentation Improvements or additions to documentation good first issue Good for newcomers labels Jun 17, 2024
@MicahGale
Copy link
Collaborator

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
Copy link
Collaborator Author

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
Copy link
Collaborator

MicahGale commented Jun 17, 2024

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
Copy link
Collaborator

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
Copy link
Collaborator

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

@tjlaboss
Copy link
Collaborator Author

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

@MicahGale
Copy link
Collaborator

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

@tjlaboss
Copy link
Collaborator Author

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.

@MicahGale
Copy link
Collaborator

related to #559.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers
Projects
None yet
Development

No branches or pull requests

2 participants