docs: restructure for better sidebar#290
Merged
jdecarolis merged 11 commits intounstablefrom Apr 2, 2026
Merged
Conversation
WalkthroughDocumentation-only updates: added Database and Commodity Network pages, reorganized index and Quick Start toctrees, normalized top-level headings and footnote reference syntax across multiple pages, removed an unused Changes
Sequence Diagram(s)(omitted — changes are documentation-only and do not introduce new multi-component control flow) Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/source/database.rst`:
- Around line 109-111: Replace the deprecated reference
"data_files/example_dbs/utopia.sql" with the current maintained starter
workflow/path; update the sentence to point users to
"data_files/temoa_schema_v4.sql" (or the project’s maintained example
DB/workflow) so new users are directed to the supported schema; update any
adjacent text that suggests using the old example to instead reference the
maintained schema file and workflow.
In `@docs/source/preface.rst`:
- Around line 65-67: Move the "Preface" top-level heading to the very top of the
file so it becomes the document title, then convert "What is Temoa?" into a
subsection under Preface (e.g., use a suitable subsection underline style
shorter than the top-level or add a small underline like "----" to make it a
subsection), ensuring heading underline lengths match the heading text and the
structure places "What is Temoa?" beneath "Preface".
In `@docs/source/references.rst`:
- Around line 42-71: Update all external reference targets in
docs/source/references.rst to use HTTPS where the remote site supports it:
replace "http://" with "https://" for entries such as _WinGLPK, _Temoa model,
_temoaproject.org, _example data sets, _HTML, _available (Stanford cvxbook),
_quick start guide, _sqlite, _Graphviz, etc.; for each underscore-label (e.g.,
"WinGLPK", "Temoa model", "temoaproject.org") verify the HTTPS endpoint works
and leave the original HTTP only if HTTPS is unavailable, then commit the
changed reference URLs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: e12fd2d5-ca61-4b8a-abff-55e8afa242e0
⛔ Files ignored due to path filters (4)
docs/source/assets/logo.pdfis excluded by!**/*.pdfdocs/source/assets/logo.svgis excluded by!**/*.svgdocs/source/assets/logo_bottom_text.pdfis excluded by!**/*.pdfdocs/source/assets/logo_bottom_text.svgis excluded by!**/*.svg
📒 Files selected for processing (9)
docs/source/computational_implementation.rstdocs/source/conf.pydocs/source/database.rstdocs/source/index.rstdocs/source/mathematical_formulation.rstdocs/source/preface.rstdocs/source/quick_start.rstdocs/source/references.rstdocs/source/visualization.rst
💤 Files with no reviewable changes (1)
- docs/source/conf.py
Collaborator
|
@ParticularlyPythonicBS -- This looks really good. A few minor requests:
|
ParticularlyPythonicBS
force-pushed
the
docs_restructure
branch
from
5eaf52d to
1b949de
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/source/commodity_network.rst`:
- Line 40: Fix spelling and wording typos in the user-facing sentence "provided
to the model freely without a preceding processing chain if there is not one
avaialbe." by correcting "avaialbe" to "available" and improving phrasing for
readability (e.g., "provided to the model without a preceding processing chain
if none is available."). Also review and correct the similar typos and wording
issues at the other mentioned occurrences (lines referenced in the review) to
ensure consistency and searchability throughout the commodity_network.rst
document.
In `@docs/source/database.rst`:
- Line 48: In the narrative sentence "modeler doesn't accidently type the wrong
label in this table." (and the duplicate at the other occurrence), correct the
spelling by changing "accidently" to "accidentally" and ensure the sentence
reads "modeler doesn't accidentally type the wrong label in this table."; update
both occurrences so the user-facing copy is correct.
- Around line 123-127: Update the documentation that currently claims the ``<``
redirection operator works in PowerShell: state that PowerShell does not support
Unix-style ``<`` stdin redirection and replace the misleading cross-shell claim,
then provide cross-platform alternatives such as using SQLite's interactive
".read" command (with ``sqlite3``) and a PowerShell-safe pipeline alternative
(e.g., reading the file and piping into ``sqlite3``); reference the existing
mention of the ``<`` operator and the ``sqlite3`` client so reviewers can find
and update the paragraph.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 41e9a146-0f95-4907-9149-69ea60f99e53
📒 Files selected for processing (5)
docs/source/commodity_network.rstdocs/source/database.rstdocs/source/index.rstdocs/source/monte_carlo.rstdocs/source/quick_start.rst
There was a problem hiding this comment.
♻️ Duplicate comments (2)
docs/source/database.rst (2)
48-48:⚠️ Potential issue | 🟡 MinorUser-facing spelling errors remain in narrative text.
Please correct
accidently→accidentallyandprogramatically→programmatically.Also applies to: 58-58
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/source/database.rst` at line 48, Fix the user-facing spelling mistakes in docs/source/database.rst by replacing "accidently" with "accidentally" and "programatically" with "programmatically"; search the file for the exact misspellings (notably the occurrences around the current diff, e.g., the "accidently" instance shown and the other occurrence at the file's line ~58) and update them so the narrative text uses the correct spellings.
123-125:⚠️ Potential issue | 🟠 MajorIncorrect PowerShell compatibility claim for
<redirection.This still states PowerShell supports Unix-style stdin redirection with
<, which is incorrect and will fail for users following the docs.Does Windows PowerShell (5.1 and 7+) support Unix-style stdin redirection with `<` for native commands like `sqlite3 my_database.sqlite < my_database.sql`? What is the recommended cross-version alternative?🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/source/database.rst` around lines 123 - 125, The docs incorrectly claim PowerShell supports the Unix-style ``<`` stdin redirection; update the sentence referencing the ``<`` operator (and the example `sqlite3 my_database.sqlite < my_database.sql`) to say that ``<`` is supported in most Linux/macOS shells and in Windows Command Prompt, but not in Windows PowerShell; provide the cross-version PowerShell-safe alternative using piping such as `Get-Content my_database.sql | sqlite3 my_database.sqlite` (or the `type my_database.sql | sqlite3 my_database.sqlite`/`gc` alias) and keep the note about using correct Windows path separators.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/source/database.rst`:
- Line 48: Fix the user-facing spelling mistakes in docs/source/database.rst by
replacing "accidently" with "accidentally" and "programatically" with
"programmatically"; search the file for the exact misspellings (notably the
occurrences around the current diff, e.g., the "accidently" instance shown and
the other occurrence at the file's line ~58) and update them so the narrative
text uses the correct spellings.
- Around line 123-125: The docs incorrectly claim PowerShell supports the
Unix-style ``<`` stdin redirection; update the sentence referencing the ``<``
operator (and the example `sqlite3 my_database.sqlite < my_database.sql`) to say
that ``<`` is supported in most Linux/macOS shells and in Windows Command
Prompt, but not in Windows PowerShell; provide the cross-version PowerShell-safe
alternative using piping such as `Get-Content my_database.sql | sqlite3
my_database.sqlite` (or the `type my_database.sql | sqlite3
my_database.sqlite`/`gc` alias) and keep the note about using correct Windows
path separators.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 71330d51-2b17-42ad-97e1-ee4ea0de442e
📒 Files selected for processing (2)
docs/source/database.rstdocs/source/quick_start.rst
ParticularlyPythonicBS
force-pushed
the
docs_restructure
branch
from
1b949de to
6c30c2c
Compare
Member
Author
Done! Also added windows compatible instructions wherever needed |
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (2)
docs/source/commodity_network.rst (1)
139-141:⚠️ Potential issue | 🟡 MinorCorrect typo: “were” → “where”.
Line 140 currently says “myopic actions were a technology…”, which should be “where”.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/source/commodity_network.rst` around lines 139 - 141, Fix the typo in the documentation text where the phrase "myopic actions were a technology in a chain is not selected for build" uses "were"; replace "were" with "where" so it reads "myopic actions where a technology in a chain is not selected for build". Ensure the corrected word appears in the sentence that contains "non-utilized outputs may be the result..." so the sentence reads grammatically correct.docs/source/database.rst (1)
58-58:⚠️ Potential issue | 🟡 MinorFix spelling: “programatically” → “programmatically”.
This is user-facing copy and appears misspelled on Line 58.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/source/database.rst` at line 58, Replace the misspelled word "programatically" with the correct spelling "programmatically" in the sentence that reads "perform thousands of runs, programatically store all the results, and execute" so the copy becomes "perform thousands of runs, programmatically store all the results, and execute"; update the source text where that exact phrase appears to fix the user-facing typo.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/Makefile`:
- Around line 106-125: The Makefile's help text still references "pdflatex" even
though the latexpdf target now uses xelatex; update the help/usage text that
mentions pdflatex to say xelatex (and adjust any variable descriptions that
mention PDFLATEX invoking pdflatex) so the displayed help matches the latexpdf
target behavior; locate references near the latexpdf target and any lines that
document PDFLATEX or latex engine in the help output and replace "pdflatex" with
"xelatex" (and update related wording for PDFLATEX variable if needed).
In `@docs/source/commodity_network.rst`:
- Around line 30-31: Fix the grammar in the sentence that currently reads "In
order enforce conservation of flow constraints" in
docs/source/commodity_network.rst by adding the missing "to" (e.g., "In order to
enforce conservation of flow constraints") or rephrasing to "To enforce
conservation of flow constraints" so the line reads smoothly when describing how
the model identifies output flows (commodities) and demand.
In `@docs/source/index.rst`:
- Around line 8-12: The sidebar currently uses the target page title for the
entry 'commodity_network'; change the toctree entry to use an explicit label so
the sidebar shows "Network Flow" (e.g., replace the bare 'commodity_network'
list item with a labeled entry like "Network Flow <commodity_network>" in
docs/source/index.rst) so the sidebar text matches the requested wording.
In `@docs/source/references.rst`:
- Around line 55-56: Replace the date-stamped PDF link for the PDF reference in
docs/source/references.rst (the ".. _PDF:" anchor) with a stable "latest" or
canonical PDF endpoint/alias (e.g., a /latest or /current PDF URL) so the PDF
reference does not become stale; update the URL while keeping the ".. _PDF:"
anchor name unchanged.
---
Duplicate comments:
In `@docs/source/commodity_network.rst`:
- Around line 139-141: Fix the typo in the documentation text where the phrase
"myopic actions were a technology in a chain is not selected for build" uses
"were"; replace "were" with "where" so it reads "myopic actions where a
technology in a chain is not selected for build". Ensure the corrected word
appears in the sentence that contains "non-utilized outputs may be the
result..." so the sentence reads grammatically correct.
In `@docs/source/database.rst`:
- Line 58: Replace the misspelled word "programatically" with the correct
spelling "programmatically" in the sentence that reads "perform thousands of
runs, programatically store all the results, and execute" so the copy becomes
"perform thousands of runs, programmatically store all the results, and
execute"; update the source text where that exact phrase appears to fix the
user-facing typo.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: df81f68e-78cb-4e21-8e48-feb51972874d
📒 Files selected for processing (7)
docs/Makefiledocs/source/commodity_network.rstdocs/source/conf.pydocs/source/database.rstdocs/source/index.rstdocs/source/quick_start.rstdocs/source/references.rst
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/source/preface.rst`:
- Around line 120-121: Replace the escaped-space before the period after the
inline link: locate the text "Issue tracker`_\ ." and remove the backslash and
space so it reads "Issue tracker`_." ensuring the reStructuredText link markup
uses `Issue tracker`_. exactly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8c17dfec-62c3-4b76-b374-170ab27e0d9b
📒 Files selected for processing (5)
docs/Makefiledocs/source/commodity_network.rstdocs/source/database.rstdocs/source/preface.rstdocs/source/references.rst
Comment on lines
120
to
+121
| If you are a software developer-type, feel free to open an issue on our `GitHub | ||
| Issue tracker`_\ . If you would rather not create a GitHub account, feel free | ||
| to let us know the issue on our `mailing list`_\ . | ||
| Issue tracker`_\ . |
There was a problem hiding this comment.
Remove the escaped-space before punctuation after the link.
Line 121 currently uses Issue tracker`_\ .`, which may render awkward spacing before the period. Use Issue tracker`_.`` instead.
✏️ Proposed fix
-If you are a software developer-type, feel free to open an issue on our `GitHub
-Issue tracker`_\ .
+If you are a software developer-type, feel free to open an issue on our `GitHub
+Issue tracker`_.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| If you are a software developer-type, feel free to open an issue on our `GitHub | |
| Issue tracker`_\ . If you would rather not create a GitHub account, feel free | |
| to let us know the issue on our `mailing list`_\ . | |
| Issue tracker`_\ . | |
| If you are a software developer-type, feel free to open an issue on our `GitHub | |
| Issue tracker`_. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/source/preface.rst` around lines 120 - 121, Replace the escaped-space
before the period after the inline link: locate the text "Issue tracker`_\ ."
and remove the backslash and space so it reads "Issue tracker`_." ensuring the
reStructuredText link markup uses `Issue tracker`_. exactly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit