-
Notifications
You must be signed in to change notification settings - Fork 40
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
Markdown parsing #547
Markdown parsing #547
Conversation
Thinking of adding the following as a shell script or makefile: @whoburg, thoughts? for var in $@; do
python -c "import gpkit; exec gpkit.mdmake(\"$var\")"
if [ -e "default.latex"]; then
pandoc -c "pandoc -o $var.pdf $var --template default.latex
else
pandoc -c "pandoc -o $var.pdf $var
done
done |
Also keeping an eye open for ways we could indicate that for the PDF a particular code block should be removed or replaced by a particular Currently thinking that if the first line of a python block is |
Implemented the above in latest commit, updated PDF is here: gas_hale.pdf In the |
I'm digging the idea of starting with code and incrementally replacing it with latex that describes it: the bits of the PDF that are still code are the bits that need more documentation work... @pgkirsch, you're the expert on gpkit papers, does this seem reasonable? (with an overall tex file that imports all the submodel texs, etc.) |
hmmm this is an interesting idea, and seems like it could be really helpful for documentation and paper writing. A couple initial reactions:
That probably sounds really negative, sorry. I think it's cool stuff and really nice for auto-generating documentation, but is there really a demand for it yet when we can't even debug models that don't work/don't have that many models in our model library? |
Good points! re 1, this experiment is definitely a little premature. :) But Woody and I were looking at the 16.82 repo and saw latex documentation of models which was just copy-pasted comments variables and constraints, so it might be immediately useful. re 2, One nice thing about this is that it doesn't add any new python syntax. But, re 3, it does increase the complexity of the model file by incorporating more documentation into it. The hope is that this reduces the overall difficulty of documenting a model (see for instance the picture you posted for the atmospheric model) and the likelihood that documentation and code will slip out of sync. re your last paragraph, I think we need to start early with good documentation of the models in our library. The atmospheric model's been great for this, with citations and graphs, and this might be a way to normalize that kind of model documentation. |
retest this please |
Great to see an initial proposal for how to tie together model implementation with documentation / derivation. A few thoughts:
|
@@ -26,6 +26,30 @@ | |||
SETTINGS_PATH = os_sep.join([os_path_dirname(__file__), "env", "settings"]) | |||
|
|||
|
|||
def mdparse(filename): |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
docstring
one more comment: it feels a bit awkward to have the python implementation of a particular class ( |
re your last comment, it does feel a little funny, but I think it helps when reading the markdown. And yeah, it'd happen a lot less with model composition. :) |
Can one of the admins verify this patch? |
test this please |
|
I think it would make sense to move |
Sounds like a good plan! The pandoc error is because you didn't use the template including |
should that template be added to gpkit? |
In gpkit-models? Quite possibly. In gpkit? I don't know...and what about the shell script? |
This commit was merged into #493, closing |
This PR allows a markdown file to be run as python code. For example:
will run the code in this example markdown file.
This provides immediate model documentation (including plots) on Github. Check it out!
A secondary advantage is that running
pandoc -o gas_hale.pdf gas_hale.md
produces this nice pdf