Migrate additional website content

License.txt

@@ -6,7 +6,7 @@ Copyright (c) 2009 Sandia Corporation. Under the terms of
 Contract AC04-94AL85000 with Sandia Corporation, the U.S. Government
 retains certain rights in this software.
 
-Copyright (c) 2011-2023, Cantera Developers.
+Copyright (c) 2011-2024, Cantera Developers.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

doc/doxygen/mainpage.md

@@ -1,10 +1,7 @@
 # %Cantera C++ Reference
 
-> **Note:** This is the **%Cantera Developer API** documentation; for general
-> information on %Cantera, refer to [**cantera.org**](https://cantera.org).
-
-Use sidebar or menu at the top to view detailed documentation of the code, or
-use the following shortcuts:
+Use the sidebar to view detailed documentation of the C++ code, or use the following
+shortcuts:
 
 * Overview of [**Cantera C++ Modules**](modules.html)
 * Index of [**Cantera C++ Classes**](classes.html)
@@ -19,8 +16,8 @@ A topical overview is provided as follows:
 * @ref onedGroup (flames, flow domains, boundaries, ...)
 * @ref physConstants (universal constants, built into %Cantera for convenience)
 
-For fundamental scientific theory used for the implementation of %Cantera, refer to the
-[Cantera Science Section](https://cantera.org/science/index.html) of the
-[Cantera Website](https://cantera.org).
+Details on the fundamental scientific theories used in the implementation of %Cantera
+are located in the
+[Science Reference Section](../reference/index.html#science-reference).
 
 The %Cantera source code is hosted on [GitHub](https://github.com/Cantera/cantera).

doc/sphinx/conf.py

@@ -223,7 +223,13 @@ def escape_splats(app, what, name, obj, options, lines):
     'pint': ('https://pint.readthedocs.io/en/stable/', None),
 }
 
-myst_enable_extensions = ["dollarmath", "amsmath", "deflist", "colon_fence"]
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "deflist",
+    "colon_fence",
+    "attrs_block",
+]
 
 mathjax3_config = {
     'tex': {
@@ -255,7 +261,7 @@ def escape_splats(app, what, name, obj, options, lines):
 
 # General information about the project.
 project = 'Cantera'
-copyright = "2001-2023, Cantera Developers"
+copyright = "2001-2024, Cantera Developers"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/sphinx/develop/compiling/dependencies.md

@@ -119,7 +119,7 @@ compiler is required only if you plan to build the Fortran module.
 
 - [Ruamel.yaml](https://pypi.org/project/ruamel.yaml/) (Python)
 
-  - Required to convert input files from Chemkin, CTI, and XML to the YAML
+  - Required to convert input files from Chemkin, {term}`CTI`, and XML to the YAML
     format
   - Known to work with versions 0.15.42, 0.15.87, and 0.16.5
   - Expected to work with versions >= 0.15.0

doc/sphinx/develop/doc-formatting.md

@@ -0,0 +1,57 @@
+# Formatting Documentation
+
+Most of Cantera's HTML documentation, with the exception of the C++ API documentation,
+is generated by [Sphinx](https://sphinx-doc.org). The C++ API documentation is generated
+using Doxygen. The content used to generate these pages comes from several sources:
+
+- [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
+  documents (with the `.rst` extension), organized under the `doc/sphinx` subdirectory
+  of the Cantera Git repository.
+- [MyST Markdown](https://myst-parser.readthedocs.io/en/latest/index.html)
+  documents (with the `.md` extension), organized under the `doc/sphinx` subdirectory of
+  the Cantera Git repository.
+- Docstrings extracted from the Python source code, which are used to generate the
+  Python API docs. These docstrings are parsed as reStructuredText.
+- Docstrings extracted from the C++ source code, which are parsed by
+  [Doxygen](https://www.doxygen.nl/manual/docblocks.html). These docstrings are
+  formatted using Doxygen's syntax, which includes support for its own flavor of
+  Markdown.
+- Markdown files, organized under the `doc/doxygen` subdirectory of the
+  Cantera Git repository, processed using Doxygen's Markdown parser.
+
+This page provides some notes on useful syntax for writing in these various formats.
+
+## Useful MyST syntax
+- Linking to a Python class: `[](#ThermoPhase)`
+  - This only works if there isn't a Matlab class with the same name!
+- Linking to a Python class: ``` {py:class}`~cantera.Wall` ```
+  - The `~` removes the `cantera` prefix from the rendered link.
+- Linking to a C++ class: ``` {ct}`ThermoPhase`  ```
+- Linking to a Doxygen page: `<a href="../cxx/d0/de3/citelist.html">link text</a>`
+  - The number of `../` required depends on how deep the source page is in the hierarchy
+- Linking to a Sphinx page:
+  - `[](/absolute-subdir/docname)` (automatically get the text from `docname`'s title)
+  - `[link text](relative-subdir/docname)` (explicitly specified link text)
+  - source file extension is optional
+- Linking to a labeled section:
+  - `[Build Commands](sec-build-commands)`
+- Labeling a section: Above the heading, write:
+  - `(sec-label-name)=`
+- To cite as "according to Smith et al \[1999]": ``` according to {cite:t}`smith1999` ```
+- To cite as "blah blah \[Smith et al 1999]": ``` blah blah {cite:p}`smith1999` ```
+- Including code from a file (here, drawing directly from the Cantera source tree; the path is relative to the temporary build directory `build/doc/sphinx/develop/reactor-integration.md`; the number of `../` will vary for files that are at depths within the `sphinx` directory):
+   ```
+   :::{literalinclude} ../../../../src/zeroD/ReactorNet.cpp
+   :start-at: "void ReactorNet::updateState"
+   :end-before: " ReactorNet::"
+   :language: c++
+   :::
+   ```
+
+## Useful reST syntax
+- Linking to a Sphinx page:
+  - `` :doc:`/absolute/path` `` (automatic name)
+- Caution on usage of single backticks versus double backticks -- the former are only for linking to things using the default role (that is, Python objects)
+
+## Useful Doxygen syntax
+- Linking to a Sphinx page: `[link text](../reference/science/phasethermo/lattice.html)`

doc/sphinx/develop/index.md

@@ -1,10 +1,6 @@
 # Develop
 
-```{caution}
-This page is a work in progress. For compilation instructions for Cantera 3.0, please
-see <a href="/install/compiling-install.html">this page</a>.
-```
-
+(sec-compiling)=
 ## Compiling Cantera from Source
 
 If you're interested in contributing new features to Cantera, or you want to try the
@@ -35,6 +31,10 @@ compiling/special-cases
 
 ## How Cantera Works
 
+```{caution}
+This section is a work in progress.
+```
+
 - [](reactor-integration)
 
 ```{toctree}
@@ -45,4 +45,17 @@ compiling/special-cases
 reactor-integration
 ```
 
-## Adding New Models to Cantera
+## Adding New Features to Cantera
+
+```{caution}
+This section is a work in progress.
+```
+
+- [](doc-formatting)
+
+```{toctree}
+:caption: Adding New Features to Cantera
+:hidden:
+
+doc-formatting
+```