Edits to improve comprehensibility of SSJ_example #1481
Conversation
|
I made some minor edits for clarity to the SSJ_example notebook, but now there's a failure in "Documentation/Render". Dominic, can you figure this out and when done ask Matt to merge? |
|
I suspect this is the same error I'm having on my branch. Something is up.
…On Tue, Aug 13, 2024, 6:17 PM Christopher Llorracc Carroll < ***@***.***> wrote:
I made some minor edits for clarity to the SSJ_example notebook, but now
there's a failure in "Documentation/Render". Dominic, can you figure this
out and when done ask Matt to merge?
—
Reply to this email directly, view it on GitHub
<#1481 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ADKRAFOSUJGJ57Z74IDBUKDZRKAWNAVCNFSM6AAAAABMPEQPUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOBXGIZTINJTGU>
.
You are receiving this because your review was requested.Message ID:
***@***.***>
|
|
This problem is the result of a change to the way Sphinx checks markdown documents. I have a fix in my doc fix branch, but I'll also make a separate pull request to fix that specific issue. |
|
We can also merge that branch if it's in a "good enough" place, and
continue with another branch.
…On Tue, Aug 13, 2024, 9:00 PM DominicWC ***@***.***> wrote:
This problem is the result of a change to the way Sphinx checks markdown
documents. I have a fix in my doc fix branch, but I'll also make a separate
pull request to fix that specific issue.
—
Reply to this email directly, view it on GitHub
<#1481 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ADKRAFOXROFSS4FODUDF4ZTZRKT4JAVCNFSM6AAAAABMPEQPUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOBXGU3DSNBYG4>
.
You are receiving this because your review was requested.Message ID:
***@***.***>
|
|
Unfortunately, I'm going to bring up something pretty big about it at tomorrows meeting, so It's not ready yet. The quick fix should be up now |
|
Oh no, how worried should I be? I just merged your small PR, then updated the two PRs from master. Let's see if that fixes it. |
|
Well, we do have the question about how to document models that don't fully work. But really I just need you're input because I have three proposals for updating the autodoc formatting. I'm going to make one of the changes (or a combo), but I don't want to make a change and then have to reverse it because there was an issue one of you could have spotted. |
|
It seems like in the process of improving this notebook, you changed some of the title's sizing. Sphinx has very particulary thoughts about the order of title sizing (that it should never decrease by more than one at a time). I'm not sure how to make edits to this PR directly, but in the notebook, the line that says "#Bringing model to code" should say "##Bringing model to code", with two Hashtags. That change got the documentation to compile properly on my end. |
|
I don’t understand the Sphinx rule.
I have:
# Model
[some text]
## Model Features
[some features]
# Bringing the Model to the Code.
[more text]
It’s not decreasing by more than one at a time. So, maybe the rule is that
you can only have one single-hashtag line in the whole document, which is
like a title line?
So then everything after that needs to be two hashtags or more?
On Tue, Aug 13, 2024 at 9:34 PM DominicWC ***@***.*** ***@***.***> wrote:
It seems like in the process of improving this notebook, you changed some
of the title's sizing. Sphinx has very particulary thoughts about the order
of title sizing (that it should never decrease by more than one at a time).
I'm not sure how to make edits to this PR directly, but in the notebook,
the line that says "#Bringing model to code" should say "##Bringing model
to code", with two Hashtags.
—
Reply to this email directly, view it on GitHub
<#1481 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAKCK76ANJX7OGUXD7CN4V3ZRKXZXAVCNFSM6AAAAABMPEQPUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOBXGY3DGOJTG4>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
--
- Chris Carroll
|
|
After the line "#Bringing the model to code" you have the lines "### Calibrate Steady State Values" and "### Micro Agent Parameters" so it's going from # -> ###. You can fix this by changing the "bringing the model to code" line so that it has two # signs, or change the following two lines so that they have two # signs. Sphinx is fine with more than one single hash-tag as long as they never decrease by more than one at a time. |
|
Dominic,
Could you review the document and make a PR for the appropriate revisions?
I would not be surprised if you had other good ideas, especially with
respect to links to other elements of the toolkit.
PS. When you return to school, might you still have a little time to work
for us, say 2-4 hours a week -- basically, you have accumulated an
impressive body of knowledge about the whole documentation infrastructure
and the current status of the toolkit, and I want to be able to draw upon
you as a resource going forward (probably mostly in a consulting capacity).
…On Wed, Aug 14, 2024 at 11:01 AM DominicWC ***@***.***> wrote:
After the line "#Bringing the model to code" you have the lines "###
Calibrate Steady State Values" and "### Micro Agent Parameters" so it's
going from # -> ###.
You can fix this by changing the "bringing the model to code" line so that
it has two # signs, or change the following two lines so that they have two
# signs. Sphinx is fine with more than one single hash-tag as long as they
never decrease by more than one at a time.
—
Reply to this email directly, view it on GitHub
<#1481 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAKCK75XQOBVL4265KO5IFLZRNWNXAVCNFSM6AAAAABMPEQPUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOBZGA2TMNZZHE>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
--
- Chris Carroll
|
No description provided.