Generate a website with docs via mkdocs
#2166
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ilyagr
force-pushed
the
mkdocs
branch
4 times, most recently
from
7071569 to
4926cca
Compare
ilyagr
changed the title
mkdocsmkdocs
ilyagr
force-pushed
the
mkdocs
branch
9 times, most recently
from
fc15398 to
1e67093
Compare
ilyagr
force-pushed
the
mkdocs
branch
15 times, most recently
from
6410f35 to
d3e660b
Compare
```shell script
```
breaks mkdocs rendering
|
Thank you Philip! I addressed your comments, added some more details to I'll wait another day or two to see if anyone else has comments. I also think that ultimately @martinvonz should merge this, as he is likely to have to deal with branch protection issues when this is merged. (I don't understand exactly what the best branch protection setup for the |
ilyagr
force-pushed
the
mkdocs
branch
13 times, most recently
from
6b18e03 to
c502569
Compare
I initially was thinking of using `mdbook`, which looks a little better, but I think versioning the docs is important, and the features I want are pretty much only supported by the Mkdocs' "Material" theme. Mkdocs is written in Python. The prerequesites for building docs on your machine should be to install Python and Poetry, everything else should be installed automatically by Poetry. See the edits to `contributing.md` for more details.
This makes mkdocs compile cleanly
One action publishes the 'prerelease' version on every push to `main`. The other publishes a 'latest' version on every releasse. I tested both of them, but not with branch protection rules.
This should allow Nix users to build the documentation in `nix develop` following the instructions in `contributing.md`. It feels a little weird to add a package manager and ask people to use it inside nix, but I think it's simpler than having two sets of instructions and dependencies to maintain.
|
@martinvonz, feel free to merge this whenever you want. |
|
As expected, the branch protection rules make themselves known. https://github.com/martinvonz/jj/actions/runs/6003122517/job/16280883112#step:6:77 |
|
I've relaxed the branch protections to only require linear updates now. |
|
I asked it to "rerun failed jobs" -- and I think it worked! 🎉 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is more or less ready for review now.
You can play with the website this generates on https://ilyagr.github.io/jj (which redirects to a placeholder docs for a "released" version of jj) and https://ilyagr.github.io/jj/prerelease.
This includes a github action that updates the "prerelease" section of the website on every update to main.
I initially was thinking of using
mdbook, which looks a little better, but I think versioning the docs is important, and the features I want are pretty much only supported by the Mkdocs' "Material" theme. For example, I would have preferred to use the readthedocs theme if it could keep the URL when switching versions (jimporter/mike#81).Mkdocs is written in Python. The prerequesites for building docs on your machine should be to install Python and Poetry, everything else should be installed automatically by Poetry. See contributing.md for instructions.
(Mostly) fixes #1430.