Closed stillyslalom closed 4 years ago
I've requested a review from @zygmuntszpak
Tangentially related: the full block of documentation text (including LaTeX) is printed in response to ?imgradients
, which stretches for 12 pages when pasted into Word. I'd like to refactor the documentation to make the command line help more succinct, leaving the full explanation for web only, but I'm not familiar with how the auto-doc generator works. Any pointers?
It might be worth opening a new issue for that. The documentation is built with Documenter.jl
. You may also want to read the relevant section in the Julia manual.
The documentation is lifted from the docstring associated with the function so its what you see for both the console and online. I wrote the documentation with a primarily online reading audience in mind, but people that read it from the console don't like it because it looks ugly and long in the console.
There are also two different philosophies when it comes to the documentation. Some want a minimalist approach, where the documentation is described as tersely as possible, whereas I aim for more detail so that a user of the API can have a better understanding of what the algorithm actually does. I think @johnnychen94 is in (your?) terse camp. One compromise we have been thinking about is to make use of his DemoCards
project and to put the detailed explanation of the algorithm and its parameters in a demo
, and link to it from the docstring. It took a long time and effort to write the documentation, so I would prefer if it didn't just disappear into the ether...
Yes, I prefer to have shorter console docstrings and move those lengthy explanations to HTML.
FYI, some current (not well-built) examples using DemoCards are:
More specifically, the idea is to host the docstring, the detailed explanation, and the demo codes in these cards. But to do this I need to make DemoCards.jl better first so that I'm not the only user of it 😄
The lengthy docstrings here are the impetus for https://github.com/JuliaLang/julia/issues/25930. The extensive explanations are wonderful if you use Jupyter or Juno, but they sometimes get in the way when you're wanting to do something quick at the REPL.
Codecov Report
93.75% <ø> (ø)
Continue to review full report at Codecov.