search

econ-ark / HARK

Heterogenous Agents Resources & toolKit
Apache License 2.0
336 stars 199 forks source link

Edits to improve comprehensibility of SSJ_example #1481

Closed llorracc closed 3 months ago

llorracc commented 3 months ago

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?

mnwhite commented 3 months ago

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 https://github.com/econ-ark/HARK/pull/1481#issuecomment-2287234535, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADKRAFOSUJGJ57Z74IDBUKDZRKAWNAVCNFSM6AAAAABMPEQPUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOBXGIZTINJTGU . You are receiving this because your review was requested.Message ID: @.***>

DominicWC commented 3 months ago

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.

mnwhite commented 3 months ago

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 https://github.com/econ-ark/HARK/pull/1481#issuecomment-2287569487, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADKRAFOXROFSS4FODUDF4ZTZRKT4JAVCNFSM6AAAAABMPEQPUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOBXGU3DSNBYG4 . You are receiving this because your review was requested.Message ID: @.***>

DominicWC commented 3 months ago

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

mnwhite commented 3 months ago

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.

DominicWC commented 3 months ago

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.

DominicWC commented 3 months ago

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.

llorracc commented 3 months ago

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 https://github.com/econ-ark/HARK/pull/1481#issuecomment-2287663937, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAKCK76ANJX7OGUXD7CN4V3ZRKXZXAVCNFSM6AAAAABMPEQPUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOBXGY3DGOJTG4 . You are receiving this because you authored the thread.Message ID: @.***>

--

  • Chris Carroll
DominicWC commented 3 months ago

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.

llorracc commented 3 months ago

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 https://github.com/econ-ark/HARK/pull/1481#issuecomment-2289056799, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAKCK75XQOBVL4265KO5IFLZRNWNXAVCNFSM6AAAAABMPEQPUKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOBZGA2TMNZZHE . You are receiving this because you authored the thread.Message ID: @.***>

--