brittonsmith
commented
2 months ago I quite like this. It's a great way to show both APIs together in the narrative documentation. One thing it does is highlight the fact that we are missing a high level introduction to the two APIs. Would you be willing to add a short section at the very top of Integration.rst (or perhaps right under the top paragraph) that mentions the existence of the two APIs and the primary difference between them. Currently, we just link to the API reference docs, which is the only place this is mentioned explicitly. This might add just the context that feels missing to me.
Separately, when I build the PDF version I have noticed that the text inside the tabs is completely left out. I don't think it should be a blocker since I doubt people are reading the docs this way. This also seems to be on the sphinx_tabs development roadmap.
mabruzzo
I put this together mostly as an experiment with the
"sphinx_tabs"(an extension I became aware of if because I wanted to know how the the documentation for readthedocs includes tabbed content -- they use the extension).Essentially, I modified the
Chemistry Datasection of the docs to include code snippets for the Local Functions in addition to the Primary Functions. (I basically rewrote the section so that the narrative is more consistent with both sets of snippets)I think this is a nifty extension that makes it easy to describe multiple ways of doing something without requiring us to add a bunch of extra sections to describe those alternative approaches. (plus we don't have to worry about back-referencing or forward referencing between such sessions). I think that there are a few other places we could use this feature.[^1]
Let me know how you feel about this. I suppose there are a few potential cons:
Let me know what you think.
[^1]: In particular, there are a few other spots where we could describe the Local-Functions. We could also potentially describe how to use the dynamic-api for initializing chemistry_data (but that might be a little disruptive to the narrative). Perhaps more interestingly, we could illustrate the equivalent
pygracklecommands. I think we would only need to slightly reframe the narrative to do that (but, it might be easier to do if PR #195 goes through)[^2]: we could use sphinx's literalinclude directive to explicitly extract (at least some of) the code snippets from the example files. We might need to slightly restructure some of the examples, so that the structure is a little more consistent, and we would probably want to add comment-tags to be used with the directive's
:start-after:and:end-before:. But, I actually think this would make the example-files even more useful.