You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Right now blackdoc goes through the lines one by one, tries to extract code, format the code using black, then put everything back together. While this does work, extending to different file formats becomes difficult, especially when trying to extend to jupyter notebooks (json files).
There are a lot of libraries for parsing the currently supported formats (or the planned formats):
this might come with the disadvantage of slower reading since e.g. docutils does more than just reading code blocks, but using those might make the tool a bit more robust and easier to extend to new formats. Another disadvantage is that right now we're reading the files only once but we might have to read at least docstrings more often (that is if we don't restrict python files to doctest -- should be possible, rst in docstrings is rare).
The text was updated successfully, but these errors were encountered:
thinking about this again, maybe we don't have to do that? There's lots of utilities that apply black to notebooks, so we don't have to add that. markdown support would be nice, but that should be somewhat similar to rst support. We're also reading files only once: every line is classified and the appropriate extraction / reformatting functions are called, in sequence.
since those libraries are fundamentally different from how the tool currently works (especially docutils), using those would require a rewrite, which I'm not prepared to do (and the main motivation, notebook support, can be done using other tools, e.g. nbQA).
Instead, markdown support will have to be implemented in a new blackdoc.formats module.
Right now
blackdoc
goes through the lines one by one, tries to extract code, format the code using black, then put everything back together. While this does work, extending to different file formats becomes difficult, especially when trying to extend to jupyter notebooks (json files).There are a lot of libraries for parsing the currently supported formats (or the planned formats):
docutils
for parsing restructured text (rst
)ipython sphinx extension
/jupyter sphinx extension
for reading ipython / jupyter styled code blocksmarkdown-it-py
for markdowndoctest
for extracting doctest linesjson
for parsing jupyter notebooksthis might come with the disadvantage of slower reading since e.g.
docutils
does more than just reading code blocks, but using those might make the tool a bit more robust and easier to extend to new formats. Another disadvantage is that right now we're reading the files only once but we might have to read at least docstrings more often (that is if we don't restrict python files to doctest -- should be possible, rst in docstrings is rare).The text was updated successfully, but these errors were encountered: