Replies: 2 comments 4 replies
-
About declaring multiple docs: Julia has a built-in docstring system: https://docs.julialang.org/en/v1/manual/documentation/ which is awesome! but unfortunately for this project, having a single docstring per object is 'baked in' to its design. |
Beta Was this translation helpful? Give feedback.
0 replies
-
We don't necessarily need multiple docstrings -- different sections of the same docstrings could also do this. The current system already allows for showing additional info with |
Beta Was this translation helpful? Give feedback.
4 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Problem
As @dpsanders pointed out, there is not one "best" way to explain something! Some users want a technical reference, others want a tutorial, others want an example, ...
In Julia's Base documentation, the docstrings are often of the 'technical reference' kind. This is great for some users, but not for newcomers. A good example is the docstring for
rand
, leading you down a path of Mersenne twisters and random arrays, and failing to tell users thatrand()
gives a number between0
and1
.Idea
A realistic solution is not to change Julia's documentation, since we don't want the technical documentation to disappear completely. I think we need a way to have different docstrings for the same object. This means:
Localization
Another use case is localization! Can we show the documentation in a language other than English? It might be worth looking into Julia's Chinese localization, I found that the manual entries are translated, but all docstrings are still in English: https://docs.juliacn.com/latest/base/collections/
Beta Was this translation helpful? Give feedback.
All reactions