How to consistently document ARMI "things"?

[albeanth]

So we've been doing lots of documentation lately.

Should we capitalize the first letters of ARMI "things"? E.g. Components, Composites, Flags, etc. I've started doing this, but realize it creates an inconsistency that might be less than desirable.

[john-science]

I have always tried to do this, when writing docs.

The only downside is pluralization. That is, writing this seems fine:

Boy, a Component is a great thing.

But, writing this seems a little suspect:

Boy, Components sure are great.

It seems suspect to me because while a "Component" is an ARMI "thing", making plural is English grammar but not code.

[albeanth]

What if we put double asterisks around them? E.g.,

• "This Component is cool."
• "These Components are cool."

We could probably use "substitutions" too 🤔 . https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions

The rst_prolog https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog looks particularly promising

So if we had a rst_prolog with something like:

rst_prolog = """
.. |comp| replace:: Component
"""

The above examples would become:

• "This |comp| is cool."
• "These |comp|s are cool."

And those would/should render to whatever we have for the "substitution". This would be really useful if we ever wanted to change our minds with something.