-
-
Notifications
You must be signed in to change notification settings - Fork 5.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Converting the standard library to 100% Markdown #13047
Comments
This is a great list. The complexity of implementing any solution wrt to crosslinking will be dramatically reduced if the rest of the manual is converted to Markdown. Most of the reasons why so many features are used is that they link back into the manual and vice versa. |
Yeah, but I think that, regardless of the manual solution, we'll want some shorthand way to specify manual/stdlib anchors that aren't necessarily on the same page. Perhaps we could just use regular anchor syntax, and then the RST/mythical-new-manual output will reinterpret them as manual/stdlib cross references? E.g., |
Perhaps the solution for function references is to use |
julia> Markdown.parse("``has` in it``")
has` in it
(Perhaps would need a trick to work with |
Yup, I got that working last night and should have a PR for those guys this evening.
I wasn't aware it was supported. If it is: awesome! 🍰 There's only about four or five tables, so it's not high on the priority list right now.
Yeah, there's literally one use of the
|
The
Is there a method to get the docs url from the type/func/const etc. ? |
Hi |
Just an update on this: I'm currently translating the rest of the rst docstrings to markdown, tidying up and reformatting others, adding @StefanKarpinski's suggestion (#14310 (comment)) for inline LaTeX using double backticks, and removing all usage of (The diff is currently quite large, ~13000 lines, but spread over quite a few small commits to hopefully make reviewing easier.) |
+1. Do you have a plan for refs etc.? |
Please see #13308 for my work on converting RST to a variation of Markdown that I had to cobble together from conventions in GitHub Markdown, Scholarly Markdown and Pandoc Markdown. Definitely not final and I still need to modify our Markdown parser to understand the conventions and be able to render them to usable HTML. Could certainly use help. I was planning on posting a summary of what I'd decided on for conventions for things to get discussion going. |
For
and special casing the rst rendering for any url that matches |
My plan for refs was to leverage the fact that docstrings are embedded in Julia code so unlike most documentation systems, we know what |
Closed by #14378? There may be some further discussion needed for what our final ref syntax will be and perhaps some better formatting conventions in places, particularly |
There are currently
332282223218200 docstrings that haven't made the conversion to Markdown. While they still display nicely in the online manual, they are simply output as plaintext with RST markup at the terminal. Since the end goal is to have the entire manual as markdown (#12573), we will need to figure out ways of spelling the features we want in Markdown sooner or later. Here are the syntaxes that are currently used, roughly sorted by frequency of use::func:
fooand sometimes `:ref:`~ operator <~>
or:func:
f(x+y) ``):obj:
Barand sometimes `:class:`Quux
or:const:
BAZ``):exc:
ErrorException``):ref:
Link nameor auto-populated with anchor title by `:ref:`man-link-anchor
)RFC: Allow doctests in Markdown code #13045):math:
\latex`` (Convert docstrings with inline latex to Markdown #13058) — Just need to teach Markdown how to exportinline $x^2$
to RST (72 uses, very few blocked by other syntaxes).:sup:
T`` (Convert Ac_ldiv_B etc. docs to Markdown #13108) — could use unicode since its use is limited toAᵀ
and `Bᴴ` (18 uses, none blocked by other syntaxes).Manually convert bulleted lists to Markdown #13046)**Example**
s (Convert some docs with)**Example**
to Markdown #13102.. note::
) (example: gcdx)logm
,pinv
,sqrtm
,expm
,bkfact
,qrfact
,full
)(MultiMarkdown has a possible solution)Markdown just needs to be taught how to export them to RST.:literal:
has` in it``)?We probably don't really need to preserve all of Python's different ways of referencing functions/objects/classes/constants/exceptions/etc. But that is far and away the biggest reason why most RST blocks haven't been converted. If we can figure out a way to do references, we'll be 90% of the way there.
Note that if one method's docstring failed to auto-convert to markdown, none of the functions methods were converted to markdown. So when addressing one of the items above, search to see if addressing the docstring of one method frees all the other methods, too.
The text was updated successfully, but these errors were encountered: