Makie docs with Pollen and Docusaurus #2284
jkrumbiegel
started this conversation in
Ideas
Replies: 2 comments 1 reply
-
I don't know if it fits the requirements of Makie docs but quarto.org is
working nicely for me. It has support for Julia blocks and is also based on
Markdown. Besides it has nice integration with VSCode for preview and
GitHub actions ready.
Em seg., 19 de set. de 2022 06:08, jkrumbiegel ***@***.***>
escreveu:
… The Makie docs are built on Franklin, which has some problems:
- complex to understand order of operations with delayed blocks etc,
sometimes hard to debug execution errors or order effects
- website is less ergonomic than it should be, just hard to do with
limited resources which should not be spent on web design
- menus kind of fiddly to navigate
- search leads to versioned urls so that copy-pasted links mostly
expire pretty quickly
- no version notification / version switcher
- mix of html templating and content is kind of annoying
- no inbuilt interactive components
The reason why we switched from Documenter at the time was that it didn't
allow enough flexibility for handling our custom plot example blocks which
require source-rewriting to store output graphics in specified folders for
gallery access, and other things.
An idea would be to outsource the whole website generation process to an
established tool like Docusaurus, which uses markdown sources (with some
javascript sprinkled in if that's desired). This would reduce our need of
doing frontend work, as the Docusaurus community is big and it's
corporate-backed.
However, Docusaurus cannot take care of Julia-side things like code-block
execution or docstring resolution and cross-referencing. So some part of
the pipeline needs to be written in a different tool, outputting markdown
files for the downstream tool (like Docusaurus) to use.
One common thing for this pipeline to handle, is a codeblock such as
```julia
using CairoMakie
CairoMakie.activate!() # hide
Makie.inline!(true) # hide
f = Figure()
...
f
```
We want to avoid having to write out CairoMakie.activate!() etc, ideally
this would just be tagged and source-rewritten automatically. Also other
things like resetting the theme before or after each block, avoiding
accidental theme changes proliferating across examples. Also, the output
needs to be stored in svg and png if possible, making these available to
gallery creation.
To me it seems that https://github.com/lorenzoh/Pollen.jl would fit the
bill for this kind of tool, as it has a very logical tree-rewriting
approach that should make our special blocks easy to define and to
understand. It just doesn't offer markdown output currently, but this
should not be too hard to add.
One difficulty arising from this could be how multiple versions are
handled. Docusaurus wants multiple folders with markdown sources, but we
don't want to generate these markdown sources for all versions any time the
docs are built. Maybe this can still be made to work with storing html
output of the old versions, but might be more difficult to integrate with
docusaurus' version pickers. Maybe we don't really need different versions,
though. So far, these mostly led to confusion on the users' side if they
didn't access the correct versions. And there's little need usually to go
back a couple minor versions. In that case, the old markdown source could
still be accessed on github anyway.
—
Reply to this email directly, view it on GitHub
<#2284>, or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAZQW3L6CAR4F42XLHJZUO3V7AURNANCNFSM6AAAAAAQP5BMNU>
.
You are receiving this because you are subscribed to this thread.Message
ID: ***@***.***>
|
Beta Was this translation helpful? Give feedback.
1 reply
-
I agree that Pollen.jl would be a great fit for this. Let me know if there are any open questions. Regarding the versions, you can create a folder for each version and generate the files for the current version only. |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
The Makie docs are built on Franklin, which has some problems:
The reason why we switched from Documenter at the time was that it didn't allow enough flexibility for handling our custom plot example blocks which require source-rewriting to store output graphics in specified folders for gallery access, and other things.
An idea would be to outsource the whole website generation process to an established tool like Docusaurus, which uses markdown sources (with some javascript sprinkled in if that's desired). This would reduce our need of doing frontend work, as the Docusaurus community is big and it's corporate-backed.
However, Docusaurus cannot take care of Julia-side things like code-block execution or docstring resolution and cross-referencing. So some part of the pipeline needs to be written in a different tool, outputting markdown files for the downstream tool (like Docusaurus) to use.
One common thing for this pipeline to handle, is a codeblock such as
We want to avoid having to write out
CairoMakie.activate!()
etc, ideally this would just be tagged and source-rewritten automatically. Also other things like resetting the theme before or after each block, avoiding accidental theme changes proliferating across examples. Also, the output needs to be stored in svg and png if possible, making these available to gallery creation.To me it seems that https://github.com/lorenzoh/Pollen.jl would fit the bill for this kind of tool, as it has a very logical tree-rewriting approach that should make our special blocks easy to define and to understand. It just doesn't offer markdown output currently, but this should not be too hard to add.
One difficulty arising from this could be how multiple versions are handled. Docusaurus wants multiple folders with markdown sources, but we don't want to generate these markdown sources for all versions any time the docs are built. Maybe this can still be made to work with storing html output of the old versions, but might be more difficult to integrate with docusaurus' version pickers. Maybe we don't really need different versions, though. So far, these mostly led to confusion on the users' side if they didn't access the correct versions. And there's little need usually to go back a couple minor versions. In that case, the old markdown source could still be accessed on github anyway.
cc @lorenzoh
Beta Was this translation helpful? Give feedback.
All reactions