Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs to work with Read the Docs #353

Merged
merged 12 commits into from
Jul 19, 2019

Conversation

ericholscher
Copy link
Contributor

[There is a bit more background here in an email between myself & Christopher, Shauna, and Sam]

I have a branch of this building here for you to preview:

https://hark.readthedocs.io/en/eh-sphinx-updates/

It currently:

  • Documents a subset of the Python classes, building a bit off what was there before
  • Pulls in the content from a couple of the Jupyter notebooks I found
  • It has a webhook that will autobuild docs based on commit (it's running off my branch currently, but would work the same with another repo when setup)

Let me know how these look, and if you have any thoughts on how to move forward. The most obvious things for me are:

  • making sure the Python API section has all the major pieces of Python code. I can do all of them, but wasn't sure what was important
  • looking through each of the notebooks and seeing which would be most important in the docs
  • Any other small updates/additions y'all find

@llorracc
Copy link
Collaborator

This is a very good start.

Something that should be an easy improvement is that wherever readthedocs content is generated from a notebook, there should be an explicit link to a mybinder instantiation of the notebook, so that the user can view a live, interactive version of it as an alternative to the static rst rendering.

Another easy improvement is that it would be good to have at least a couple of subcategories under "Notebooks":

  • Tutorials
  • Examples and Demonstrations
  • Replications of Papers

(I will put together a list of the notebooks in each of these categories to be included for now)

The thing I would be happiest to have would be some mechanism by which it was possible for the Sphinx index to know about and link to examples of the use of the a particular tool in a designated collection of notebooks. For example, if we include the DCEGM-Upper-Envelope notebook in the set to be indexed, then it would be great to have things set up so that the documentation of, say, the function calcMultilineEnvelope function could automatically construct a link to the DCEGM-Upper-Envelope notebook as a place where the function is invoked.

The rendering of the notebooks, because it is something we have not tried before, has some problems. I'm guessing that these will need to be fixed by changing the notebook source, because whatever tool is being used to translate the notebook to rst is probably not something we can modify in ways that will fix the problems. (But, @ericholscher, could you provide a link to some documentation on the tool? Is it basically just a script that invokes jupyter nbconvert?)

Examples:

  1. The first text sentence in "Your First HARK Model: Perfect Foresight" renders as math rather than text
  2. Codefolding and various other notebook extensions do not work
    • Probably because rst does not have the ability to do something like codefolding
    • The workaround is probably to import anything that is particularly long from some source external to the notebook that is going into the readthedocs stream
  3. It appears that the LaTeX translation cannot handle \newcommand definitions like $\newcommand{\LivPrb}{\aleph}\LivPrb$ so parameters will need to be explicitly hard-coded

@llorracc
Copy link
Collaborator

I'd like to merge this today but there's a merge conflict.

Could you resolve this and let me know when it is ready? (Not sure what went wrong -- definitely the DCT-Copula-Illustration-OneAsset.py file should not be changed by this merge, so if you can replace with the master version we should be set).

@ericholscher
Copy link
Contributor Author

@llorracc I ran into this issue with a unicode character in the file while doing my testing: https://github.com/econ-ark/HARK/pull/353/files#diff-4af1295874e1dbe074f2688dc724e3c7L310 -- is that meant to be there? I can revert my change if so, but it didn't seem like valid Python to me.

@ericholscher
Copy link
Contributor Author

Looks like it was deleted in master, so I have removed my changes in this branch.

@llorracc llorracc merged commit dbc168c into econ-ark:master Jul 19, 2019
@llorracc
Copy link
Collaborator

Release notes: Moved documentation to ReadTheDocs and Sphinx

@llorracc
Copy link
Collaborator

Just noticed that our README.md still pointed to the old version of the docs. Fixed to point to draft new version.

@llorracc
Copy link
Collaborator

llorracc commented Jul 22, 2019 via email

@llorracc
Copy link
Collaborator

@ericholscher @shaunagm,

Jan Rosa has been working with me to improve the HARK documentation, and I've had him look in particular for toolkits that do a good job of guiding new users into the substance of the toolkit, by constructing curated "journeys into HARK" for people with different backgrounds. He's found some nice examples and what I would like to have him do is to create the rudiments of at least two different "journeys into HARK" -- one from the perspective of a first year PhD economics grad student, and one for someone with a lot of computer expertise but less economics grounding. I'm sending this message because if the two of you have advice for him (esp about integration of such journeys into RTD), that would be useful to him.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants