Documentation

[rjplevin]

Added documentation in preparation for a "SoftwareX" journal article on OPGEE.

[lloyd-rmi]

Can we get a rough overview of what is planned to be talked about in the SoftwareX article?

[lloyd-rmi]

Do the updates here mean that the online readthedocs will be deployed from this repo going forward?

[lloyd-rmi]

Still some comments to address but overall the updates look reasonable.

[lloyd-rmi]

Delete additional '>' around ProcessGroup

[lloyd-rmi]

Should be consist on whether you always want to have <> brackets when referring to XML elements, or if you don't want to use them at all (or only use them the first time a new element is talked about/introduced). Right now it's not completely consistent.

[rjplevin]

Good point! I will address.

Note, though, that there are many Python classes of the same name as the XML elements, so whether to include "" brackets depends on whether the element or class is being discussed.

[lloyd-rmi]

Is there a limit on the # of attributes that can be used by the csv2xml script when creating fields?

[rjplevin]

No limit.

[lloyd-rmi]

I don't know if this is just an issue with how GitHub previews these files, but this currently doesn't show up correctly when reviewing on GitHub. I can see the image successfully in the images directory though, so it might just be a GitHub thing

[mbarlow12]

This is a Sphinx/ReStrucutredText feature and goes beyond the basic Github rendering. You actually need to run sphinx-build to get the properly rendered content.

I just built the docs locally, and the image appears as expected.

[lloyd-rmi]

Is this text supposed to be tied to the figure in some way like as a sub-header? currently it just shows up as a "normal" paragraph in the preview after where the image is supposed to be.

[rjplevin]

It appears as a caption because it's indented and "within" the ..figure. You can build the docs locally by changing to the OPGEEv4/docs directory and running "make html" (at least on a Mac or in Linux. There's also a make.bat there, which I assume works, but I've never used it.)

After building the docs, you can open docs/build/html/index.html to see the resulting files.

[mbarlow12]

Do the updates here mean that the online readthedocs will be deployed from this repo going forward?

@lloyd-rmi I would support this option given the lack of permissions on the upstream repo. However, before fully committing to this, we should probably have a clearer plan for how changes in the fork will get pushed/synced with upstream.

[rjplevin]

Can we get a rough overview of what is planned to be talked about in the SoftwareX article?

It's just a basic description of the software and it's value. Wennan and Adam wanted a journal article on OPGEEv4 that could be cited in other publications. Note that Stanford is funding the development of the paper.

Rather than publish the traditional "supporting information", I decided it made more sense to include everything worth discussing directly in the readthedocs documentation.

I think it ultimately makes sense to automate the doc generation from the RMI repo, since there's no guarantee that the documentation will remain consistent with whatever the Pitt folks are doing, and which I'm not tracking.

[mbarlow12]

Left a coupe non-essential notes for additional content.

I'll also create an issue to add the auditing documentation and clean up those docstrings.

[mbarlow12]

This is a Sphinx/ReStrucutredText feature and goes beyond the basic Github rendering. You actually need to run sphinx-build to get the properly rendered content.

I just built the docs locally, and the image appears as expected.

[mbarlow12]

Would it be beneficial to add an example to show the 2 equivalent ways of creating the same input?

E.g.
Given the following in opgee.xml and attributes.xml:

<!-- opgee.xml or other template XML file -->
<Field name="my_template">
  <!-- ... other field elements -->
  <ProcessChoice name="gas_path">
    <ProcessGroup name="Minimal">
      <ProcessRef name="GasGathering" />
      <ProcessRef name="GasDehydration" />
      <StreamRef name="GasGathering => GasDehydration" />
      <StreamRef name="GasDehydration => GasPartition" />
    </ProcessGroup>
    <ProcessGroup name="Acid Wet Gas">
      <ProcessRef name="GasGathering" />
      <ProcessRef name="GasDehydration" />
      <ProcessRef name="AcidGasRemoval" />
      <ProcessRef name="Demethanizer" />
      <ProcessRef name="NGL" />
      <StreamRef name="GasGathering => GasDehydration" />
      <StreamRef name="GasDehydration => AcidGasRemoval" />
      <StreamRef name="AcidGasRemoval => Demethanizer" />
      <StreamRef name="Demethanizer => GasPartition" />
      <StreamRef name="Demethanizer => NGL" />
    </ProcessGroup>

    <ProcessGroup name="Acid Gas">
      <ProcessRef name="GasGathering" />
      <ProcessRef name="GasDehydration" />
      <ProcessRef name="AcidGasRemoval" />
      <StreamRef name="GasGathering => GasDehydration" />
      <StreamRef name="GasDehydration => AcidGasRemoval" />
      <StreamRef name="AcidGasRemoval => GasPartition" />
    </ProcessGroup>
  </ProcessChoice>
</Field>

<!-- attributes.xml -->
<ClassAttrs name="Field">
  <Options name="gas_path" default="Minimal">
    <Option desc="">None</Option>
    <Option desc="Dehydrator">Minimal</Option>
    <Option desc="Dehydrator + Amine Process">Acid Gas</Option>
    <Option desc="Dehydrator + Amine Process + Demethanizer">Acid Wet Gas</Option>
  </Options>
</ClassAttrs>

The 2 XML inputs below are equivalent.

<!-- using process choice attribute -->

<Field name="my_field" modifies="my_template">
  <A name="gas_path">Acid Gas</A>
</Field>

<!-- using explicit process/stream definitions -->

<Field name="my_field">
  <Process class="GasGathering"/>
  <Process class="GasDehydration"/>
  <Process class="AcidGasRemoval"/>
  <Stream src="GasGathering" dst="GasDehydration">
    <Contains>gas for gas dehydration</Contains>
  </Stream>
  <Stream src="GasDehydration" dst="AcidGasRemoval">
    <Contains>gas for AGR</Contains>
  </Stream>
  <Stream src="AcidGasRemoval" dst="GasPartition">
    <Contains>gas for gas partition</Contains>
  </Stream>
</Field>

[mbarlow12]

Is it possible to create a hyperlink to the test file in the github repo? I tinkered and got this to work.

... merged XML. More examples are available in the |test_merge_xml|_.

.. |test_merge_xml| replace:: ``tests/test_merge_xml.py``
.. _test_merge_xml: https://github.com/RMI/OPGEEv4/blob/main/tests/test_merge_xml.py

The link works, but it displays as any other inline code with no visual link indicator. The following gets the link highlighting but no code formatting:

`tests/tests_merge_xml.py <https://github.com/RMI/OPGEEv4/blob/main/tests/test_merge_xml.py>`_