Julia's documentation ala VitePress #53988
Conversation
|
Btw the codeblocks seem to be a bit too big on mobile, e.g.
|
|
I think it is the box that is incorrectly scaled (pretty much my fault). While expanding the docs, I had written a custom div element to surround the docs with a border, but I think the margins for that were hardcoded. We could take a look at the Documenter.jl reference div and adapt it for vitepress. |
|
A typo here? -- "Julia's" |
yeah, I changed all |
mortenpi
left a comment
There was a problem hiding this comment.
I'm not taking a stance on the UI/UX, but I do want to make a couple of maintenance points:
-
One of the core principles of Documenter is that the default writer is what the language manual uses. This ensures consistency across the ecosystem. So this should only be merged once it's integrated into Documenter.
-
Not really sure why we have the
package.jsonand.vitepressdirectory here? The build should be seamless (i.e. that you don't configure anything outside of themakedocscall). It should also not require any external dependencies to be configured (i.e. Node, which I think this currently needs?). Both should be pretty solvable though -- any temporary generator-specific files can be put into a temporary directory (like with LaTeXWriter) and externals deps should just be handled via JLLs.
For me, these would be the hard requirements for switching. Also, I know this is currently WIP and a demo, and so maybe the solutions are already on the roadmap 🙂
| ::: danger | ||
|
|
||
| This is a fork from the original repo. Please visit the [official website](https://julialang.org). | ||
|
|
||
| ::: |
There was a problem hiding this comment.
This should not work, since this is not valid Julia Markdown (well, it's valid, but should just render as text). And so if VitePress renders this, that's a bit of a problem.
There was a problem hiding this comment.
this is vitepress specific https://vitepress.dev/guide/markdown#custom-containers, but the default admonitions also work see LuxDL/DocumenterVitepress.jl#22
There was a problem hiding this comment.
From my experience with DimensionalData.jl this extra syntax is the best thing about vitepress, this is also how you make tabbed sections with very minimal work.
| ```@raw html | ||
| --- | ||
| layout: home | ||
| hero: | ||
| text: "The Julia Programming Language" | ||
| image: | ||
| light: | ||
| src: /logo.svg | ||
| alt: julia | ||
| dark: | ||
| src: /logo-dark.svg | ||
| alt: julia | ||
| actions: | ||
| - theme: brand | ||
| text: Getting Started | ||
| link: /manual/getting-started | ||
| - theme: alt | ||
| text: View on Github | ||
| link: https://github.com/JuliaLang/julia | ||
| - theme: brand | ||
| text: Sponsor | ||
| link: https://github.com/sponsors/julialang | ||
| --- | ||
| ``` |
There was a problem hiding this comment.
This is.. wrong? It's not HTML. I guess we could have an @raw vitepress maybe. But having to hack this information in like this seems wrong regardless. Seems like it should maybe be an at-meta block? That would require adding some interfaces to Documenter I think.
There was a problem hiding this comment.
I think this is actually YAML, but a general interface for arbitrary front matter would be pretty great!
There was a problem hiding this comment.
perhaps
Frontmatter = """
my raw frontmatter here...
"""
might work?
| read as: `<cond> *and then* <statement>`). Similarly, instead of `if ! <cond> <statement> end`, | ||
| one can write `<cond> || <statement>` (which could be read as: `<cond> *or else* <statement>`). |
There was a problem hiding this comment.
Should be like this I think?
| read as: `<cond> *and then* <statement>`). Similarly, instead of `if ! <cond> <statement> end`, | |
| one can write `<cond> || <statement>` (which could be read as: `<cond> *or else* <statement>`). | |
| read as: `<cond>` *and then* `<statement>`). Similarly, instead of `if ! <cond> <statement> end`, | |
| one can write `<cond> || <statement>` (which could be read as: `<cond>` *or else* `<statement>`). |
Probably worth PRing this separately.
| EC2. In this case only port 22 needs to be opened at the remote cluster coupled with SSH client | ||
| authenticated via public key infrastructure (PKI). Authentication credentials can be supplied | ||
| via `sshflags`, for example ```sshflags=`-i <keyfile>` ```. | ||
| via `sshflags`, for example * sshflags=`-i <keyfile>` *. |
There was a problem hiding this comment.
The original Markdown is correct, though, and the updated version seems like a step back.
There was a problem hiding this comment.
yes, we need to fix on the DocumenterVitepress side, I couldn't figure out the right escaping sequence in order to get something that vitepress can render. @asinghvi17, here at the bottom is the expected code by vitepress: https://luxdl.github.io/DocumenterVitepress.jl/v0.0.18/markdown-examples#Escaping-characters
There was a problem hiding this comment.
Just as a note, and related to #53988 (comment) as well, but having to sort out the escaping for everything etc. is a major drawback of the Markdown -> AST -> Markdown -> HTML approach DocumenterVitepress is taking. Getting away from all that was the major reason why we transitioned away from MkDocs in the first place back in the day.
|
It does look nice visually! I'm sure there's many tweaks to be made, but it does look beautiful (to me). |
|
Lovely! It would also be nice to bump DocumenterVitepress to at least 0.1.0, the "every release is breaking" semantic is not ideal. |
It is! The installation of Node here is purely so we can cache |
|
I have a |
|
It looks nice at first glance, but I dislike how the information density is sooo much lower. E.g. comparing https://lazarusa.github.io/JuliaDocs/manual/documentation and https://docs.julialang.org/en/v1.12-dev/manual/documentation/ on my MacBook 15" I see maybe 60% of the actual content. All this extra padding and empty lines, etc. adds up, as does the low |
|
Another thing is the low contrast, e.g. dark gray on light gray navigation menu :-(. Perhaps there are other "themes" available that avoid this pitfall? |
|
My first test was to search for |
|
That is a good point @ToucheSir. It's been working better than the regular search for some searches, but I hadn't seen this before. I am assuming that Documenter.jl is able to customize its search index here, which we haven't done with DocumenterVitepress. @mortenpi may be able to elaborate more on this. Vitepress also provides a bunch of search customization options which we can try to monkey around with in https://vitepress.dev/reference/default-theme-search. |
|
I do think DocumenterVitepress version seems prettier, but I share the concerns about readability at the cost of visual appeal. Here's a comparison between the current PR, the PR without a limit on 
While increasing the I do like the navigation bar. It makes it easier to jump to a different documentation section. My suggestion would be to replace the sidebar with "on this page". Something like the right sidebar on docs.fast.ai which doesn't draw significant visual attention. Overall though, I think the ability for DocumenterVitepress to support custom containers (e.g. before/after style code blocks) makes it much easier to write pedagogically good docs. So in support of this effort broadly. |
Currently using the fastmath vararg +, *, min, max methods only actually sets fastmath if they are specifically overloaded even when the correct 2 argument methods have been defined. As such, `ComplexF32, ComplexF64` do not currently set fastmath when using the vararg methods. This will also fix any other types, such as those in SIMD.jl, which don't overload the vararg methods. E.g. ```julia x = ComplexF64(1) f(x) = @fastmath x + x + x ``` now works correctly. I see no reason why the vararg methods shouldn't default to using the fastmath 2 argument methods instead of the non fastmath ones, which is the current behaviour. I also switched the implementation to use `afoldl` as that's what the non fastmath vararg methods use. Fixes JuliaLang#54456 and eschnett/SIMD.jl#108.
This prevents values with `:` in their name to be printed as labels. ### Before  ### After  --------- Co-authored-by: kimikage <kimikage.ceo@gmail.com>
Following https://docs.julialang.org/en/v1/manual/style-guide/#Indentation I found these with `ag "\n [^\s*#]" --julia`
Noting that the profile counters aren't atomic seems useful so I threw that in as well.
This adds a brief summary of the different output functions (`display`, `show`, `print`, `repr`, etc.) and how they interact to the custom pretty-printing section of the manual, following [this post on discourse](https://discourse.julialang.org/t/how-to-display-a-sparse-array-on-the-repl/113565/5), since people often get confused by this. --------- Co-authored-by: Max Horn <max@quendi.de>
Updating the jl_rng_split comment after a bit more consideration of the comparison with SplitMix.
Co-authored-by: Lilith Orion Hafner <lilithhafner@gmail.com>
This should be a more reliable look-up, since this will directly report the path of the currently-executing libjulia.dll. Without this PR, `LoadLibraryW` depends on the system library search order. When the top-level executable is adjacent to `libjulia.dll` (as it is for our binary distribution usually), then that search should be OK. However, applications that use Julia as a library can end up searching the system PATH before making it to the correct `lib/julia` directory, causing us to load the wrong version of `libjulia.dll`. In many cases, that extra load is benign due to the stricter separation of libraries/symbols on Windows - However, in general it's likely to be the cause of subtle bugs.
…uliaLang#54605) Fix JuliaLang#41613. Co-authored-by: FX Coudert <fxcoudert@gmail.com>
…Lang#54616) there were random cases of two and even three spaces between sentences Co-authored-by: KristofferC <kristoffer.carlsson@juliacomputing.com>
I noticed a runtime dispatch occurring in a broadcast, because the array element is specified but not the dimensions, even though the dimensions are known. With this PR, that runtime dispatch is eliminated by explicitly passing the dimensions into the type.
--------- Co-authored-by: Sukera <11753998+Seelengrab@users.noreply.github.com> Co-authored-by: Jameson Nash <vtjnash@gmail.com> Co-authored-by: Kristoffer Carlsson <kcarlsson89@gmail.com>
…Lang#54634) This avoids a: `error: non-private labels cannot appear between .cfi_startproc / .cfi_endproc pairs` error. That error was introduced in https://reviews.llvm.org/D155245#4657075 see also llvm/llvm-project#72802
This commit makes it possible for `names` to return `using`-ed names as
well:
```julia
julia> using Base: @assume_effects
julia> Symbol("@assume_effects") in names(@__MODULE__; usings=true)
true
```
Currently, to find all names available in a module `A`, the following
steps are needed:
1. Use `names(A; all=true, imported=true)` to get the names defined by
`A` and the names explicitly `import`ed by `A`.
2. Use `jl_module_usings(A)` to get the list of modules `A` has
`using`-ed and then use `names()` to get the names `export`ed by those
modules.
This method is implemented in e.g. REPL completions, but it has a
problem: it could not get the names explicitly `using`-ed by `using B:
...` (JuliaLang#36529, JuliaLang#40356, JuliaDebug/Infiltrator.jl#106, etc.).
This commit adds a new keyword argument `usings::Bool=false` to
`names(A; ...)`, which, when `usings=true` is specified, returns all
names introduced by `using` in `A`.
In other words, `usings=true` not only returns explicitly `using`-ed
names but also incorporates step 2 above into the implementation of
`names`.
By using this new option, we can now use
`names(A; all=true, imported=true, usings=true)` to know all names
available in `A`, without implementing the two-fold steps on application
side.
As example application, this new feature will be used to simplify and
enhance the implementation of REPL completions.
- fixes JuliaLang#36529
Co-authored-by: Nathan Daly <NHDaly@gmail.com>
Co-authored-by: Sebastian Pfitzner <pfitzseb@gmail.com>
…uliaLang#54610) The new feature `usings=true` added to `names` enhances REPL completions by allowing explicitly `using`-ed names to be found. ```julia julia> using Base: @assume_effects julia> @assu| # completes to `@assume_effects` ``` As a result, the implementation of REPL completions has been simplified. Additionally, it allows completion for names that are implicitly or explicitly `using`-ed in code specifying a module explicitly, such as: ```julia julia> module A end julia> A.signi| # completes to `A.significand` ``` - fixes JuliaLang#29275 - fixes JuliaLang#40356 - fixes JuliaLang#49109 - fixes JuliaLang#53524
…ang#54635) We may use aggressive constprop in `trevc!` to eliminate branches, which makes the return type of `eigvec(::UpperTriangular)` concretely inferred. ```julia julia> @inferred eigvecs(UpperTriangular([1 0; 0 1])) 2×2 Matrix{Float32}: 1.0 -0.0 0.0 1.0 ```
|
The Git history is messed and it now contains hundreds of unrelated commits |
Take a look at the preview and test the navigation and search capabilities:
https://lazarusa.github.io/JuliaDocs/
I just wanna to share how the Julia docs could look like with vitepress. If this is something worth of consideration, please help 😄 (easter holidays are over).
Some issues.
PRs for styling at https://github.com/lazarusA/JuliaDocs or here in this PR.