POC of using sphinx + pydantic #614
Conversation
|
great stuff @Tomaz-Vieira , Thanks! |
|
Hi! It's very similar to what I added in my PR. As said before, I think we should find a way of making this much simpler, organised and human-readable. If you know how to do that with sphinx, I'm happy to help. I couldn't get much further than this
|
|
That looks great, @esgomezm ! Whatever I tried on my end it seemed like it would always leave out some fields, but yours looks pretty complete =) I guess even too complete, since we can see also the It's nice that we can produce these docs, but I'm skeptical as to how much it'll solve our issue; The user-facing, tutorial-like strings would still have to live somewhere next to the docstrings, but such friendly instructions might feel out of place in the midst of the source code. Also, if we write that documentation somewhere else, then it makes it easier for it to go out of sync with the spec itself. My interest with this is that I would like to put very polite tooltips in the model builder GUI to orient users into building their models, and in a perfect world I'd be able to fetch some of that text from this endeavor. That might require tagging the text somehow so that it can be later extracted and potentially ignored when creating the more blunt developer documentation |
|
Hi @Tomaz-Vieira , I also have no experience with sphinx. It was a quick try =) In any case, I fully agree with your. This still needs further plain text description for either a GUI or human readable documentation. Unless someone knows very well how to edit sphinx and its descriptions, I would rather generate a json file. For now, by the way, I have some code that creates a drafted json like this:
|
|
Well, that does look very friendly. What is your strategy for actually producing the text here? And how does it "attach" to the spec itself? |
|
I basically parsed the json schema generated by the pydantic code from the core library. It's the one in gh-pages branch. I can make a PR. Basically it's a loop through the dictionary keys for which we can add any sort of conditions and text :) |
|
I wonder if we couldn't attach this information directly to the pydantic models, so that we skip one (potentially lossy) transformation to the Json schema, and so that it's harder for the extra text to go out of sync with the spec |
This demonstrates how we could use sphinx to do documentation, embedding the docstring-based documentation for the pydantic models into the more human-ffriendly, manually written text