Updated reference manual

[murrayrm]

This PR updates the sphinx configuration file and reference manual structure to make a number of improvements:

• All references to BioCRNpyler objects in both the user guide and docstrings should now properly link to the numpydoc formatted pages for that class and/or method.

• The reference manual now uses autosummary tables to list classes for each module, which includes a short summary in addition to the class name.

• Updated the tutorials (Jupyter notebooks) to fix various warnings and use proper sectioning commands so they appear in the user guide correctly.

• Fixed all warnings generated by sphinx (at least on my local machine; readthedocs still seems to get confused about some of the included files, but resolves things correctly).

• Added a custom template for class autosummaries that lists methods as a table after the notes section (followed by the actual docstrings for each method).

• The class descriptions are now of the form biocrnpyler.<subpkg>.class where subpkg is 'core', 'components', 'mechanisms', or 'mixtures'. Aliases are set up so that the subpkg can be ignored in references (so Species will point to core.Species).

• Preprocessing code is included to allow various conversions of simplified docstring formatting to formatted mathematics, such as converting '<-->' to $\rightleftharpoons$. See the Developer Notes in the documentation for a full description.

Some smaller changes (not all implemented systematically):

• When referring to components, mechanisms, and mixtures without referring to them explicitly as a class, I changed from capitalized to lower case. I think this reads better.

To see what the new format looks like, use the following links:

• Home page: more or less the same
• Reference manual: restructured to use autosummary tables
• Sample class pages:
  • Component: Enzyme
  • Mechanism: Energy_Transcription_MM
  • Mixture: SimpleTxTlExtract
• Tutorials: added selected advanced tutorials

[ayush9pandey]

This looks good to me. I've pushed some minor updates and formatting fixes here: murrayrm#1

[murrayrm]

I'm having a few local issues that I want to resolve before merging this:

• Math is not getting rendered correctly under sphinx (likely a version issue on my machine)
• ruff check generates lots of errors (mainly lines > 78 characters)
• Some reactions not yet converted to match (<--> instead of \leftrightarrow)
• Plain text version is ugly (\leftrightarrow instead of <-->)

I'm not sure I can/should resolve the last one, but I may play with a few things (like processing the docstrings to convert <--> when sphinx is run). I'll check these off the list as I get them resolved.

[ayush9pandey]

• Plain text version is ugly (\leftrightarrow instead of <-->)

I'm not sure I can/should resolve the last one, but I may play with a few things (like processing the docstrings to convert <--> when sphinx is run). I'll check these off the list as I get them resolved.

I agree that we lose readability of the docstrings for better math rendering. It would be great if sphinx could read --> and <--> as \rightarrow and \leftrightarrow in the docstrings.

[murrayrm]

I've added preprocessing code to allow docstring text to be converted into mathematical notation during sphinx compilation. This allows the use of simple docstrings that still look OK in text.

Description of changes (from Developer Notes):

• Mathematical equations in docstrings can be written using LaTeX
  syntax. Inline equations should be enclosed in a single set of
  dollar signs ($), with no space before or afer the equation (so
  $A + B --> C$ to produce $\text{A} + \text{B} \rightarrow \text{C}$. Displayed
  equations can be written in one of two ways:

  text
  
      $$ A + B --> C $$
  
  text
  

  or

  text
  $$
      A + B --> C
  $$
  text
  

  both of which will produce:

  $$\text{A} + \text{B} \rightarrow \text{C}$$

  The first form is prefered when the contents fit on a single line.
  The second form can be used for equations that require more than one
  line in the docstring. Multi-line formulas are also possible, using
  standard aligned syntax from LaTex.

• Several string substitutions are implemented on equation to allow
  docstrings that are easier to read in plain text while being
  formatted in LaTex for sphinx-processed documentation:

  • --> becomes $\rightarrow$
  • <--> becomes $\rightleftharpoons$
  • ... becomes $\dots$
  • >> becomes $\gg$
  • << becomes $\ll$
  • A:B becomes $\text{A:B}$ (no space)

  In addition, any strings contained in single quotes will be
  converted to text:

  $$ 'substrate' + 'enzyme' --> 'substrate':'enzyme' $$
  

  becomes:

  $$\text{substrate} + \text{enzyme} \rightarrow \text{substrate} \mathord{:} \text{enzyme}$$

  Note: docstrings are processed line by line, so any inline equations
  (single $) must appear in the same line.

• As a general rule, chemical species in reactions should be in regular
  (non-math) font. For chemical species that appear in regular text, no
  annotations are required. For chemical species in equations, use single
  quotes to allow the preprocessing to convert to text. When refering to
  the concentration of a chemical species, use square brackets ([A]; the
  chemical species will automatically be converted to regular text).

[murrayrm]

Planning to merge this later today (1 Dec) since I have another PR that builds on this one (related to parameters).