-
Notifications
You must be signed in to change notification settings - Fork 482
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
Add selector argument to deploydocs #813
Conversation
5f04725
to
8ce2d6d
Compare
src/Documenter.jl
Outdated
gitrm_copy(target_dir, stable_dir) | ||
Writers.HTMLWriter.generate_siteinfo_file(stable_dir, "stable") | ||
if version >= maxver && version.prerelease == () && in("stable", selector) | ||
cd(dirname) do; symlink(tag, "stable"); end |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note to self: This should be removed.
8ce2d6d
to
04d6def
Compare
src/Documenter.jl
Outdated
|
||
# generate the symlinks | ||
cd(dirname) do | ||
foreach(kv -> symlink(kv.second, kv.first), symlinks) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Need to remove existing links here. And I guess error if what exist there is not an old symlink?
3da546e
to
1a622e6
Compare
Ok, things seem to work now, so this should be ready for review. |
1a622e6
to
526489b
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A few tiny things, but this looks great overall!
src/Writers/HTMLWriter.jl
Outdated
|
||
# write version file | ||
function generate_version_file(dir::AbstractString, selector_entries) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since we're not using the directory as such here anymore, maybe we should change the argument to be the filename?
src/Documenter.jl
Outdated
- `"v#.#.#"`: expands to all released versions. | ||
- A string which maps directly to an existing folder. | ||
- A pair, e.g. `"first" => "second"`, which will put `"first"` in the selector, and point it | ||
to the folder called `"second"`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So it creates a symlink ln -s second/ first/
? This might be a bit misleading, since the URL will still be first/
. Might be better to say "has the same contents as "second"?
src/Documenter.jl
Outdated
@@ -316,6 +317,16 @@ documentation. By default this value is set to `"master"`. | |||
**`devurl`** the folder that in-development version of the docs will be deployed. | |||
Defaults to `"dev"`. | |||
|
|||
**`selector`** determines content and order of the resulting version selector in | |||
the generated html. The following entries are valied in the `selector` vector: | |||
- `"stable"`: points to the latest released documentation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How would you change the name of the stable/
directory? "new-name" => "stable"
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, maybe introduce a token like "v^.^.^"
to indicate maximum version, and the default here could be "stable" => "v^.^.^"
?
src/Documenter.jl
Outdated
- `"stable"`: points to the latest released documentation. | ||
- `"v#"`: expands to the latest documentation for each major release (i.e. `v1.1`, `v2.0`). | ||
- `"v#.#"`: expands to the latest documentation for each minor release (i.e. `v1.0`, `v1.1`, `v2.0`). | ||
- `"v#.#.#"`: expands to all released versions. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe better to say "includes links to the latest version for major/minor version"?
test/htmlwriter.jl
Outdated
versions = ["stable", "dev", | ||
"2.1.1", "v2.1.0", "v2.0.1", "v2.0.0", | ||
"1.1.1", "v1.1.0", "v1.0.1", "v1.0.0", | ||
"0.1.1", "v0.1.0"] # note no `v` on first ones |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is the difference of the directories with and without v
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
0.1.1
is a valid tag so there might be folders in there with that naming convention. Just include that here to make sure we dont symlink to something v0.1.1
in this case, but to 0.1.1
526489b
to
297c30d
Compare
Thanks for the review. I pushed a much simplified (?) version. Now only the following things are allowed:
Thus, removed the special casing of |
src/Documenter.jl
Outdated
@@ -316,6 +317,18 @@ documentation. By default this value is set to `"master"`. | |||
**`devurl`** the folder that in-development version of the docs will be deployed. | |||
Defaults to `"dev"`. | |||
|
|||
**`selector`** determines content and order of the resulting version selector in | |||
the generated html. The following entries are valied in the `selector` vector: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just bikeshedding here now -- since the selector
also defined which symlinks (i.e. which public URLs) get deployed, maybe it should be called something like versions
? It's not only the selector.
I would also mention here that it creates the URLs the person reading the docs sees and should use.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like versions
.
src/Documenter.jl
Outdated
- `"v#.#"`: includes links to the latest documentation for each minor release cycle | ||
(i.e. `v1.0`, `v1.1`, `v2.0`). | ||
- `"v#.#.#"`: includes links to all released versions. | ||
- `"v^"`: includes a link to the maximum version. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What does it put in the selector though? Or can you just use this in a pair?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It will put vX.Y
for latest X
and Y
, and symlink to vX.Y.Z
for latest Z
.
src/Documenter.jl
Outdated
- `"v^"`: includes a link to the maximum version. | ||
- A pair, e.g. `"first" => "second"`, which will put `"first"` in the selector, | ||
with the same content as `"second"`. The second argument can be `"v^"`, to | ||
point to the maximum version docs (as in e.g. `"stable" => "v^"`). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ditto as above w.r.t. URLs. It not only puts something into the selector, but also defines the URL you can access "second" from.
297c30d
to
9e6a85d
Compare
I changed |
the content, and order, of the version selector. The argument is a vector, defaulting to ["stable" => "v^", "v#.#", devurl => devurl]. Arguments to the selector can be: - "v^": expands to the latest release. - "v#": expands to latest doc per major release. - "v#.#": expands to latest doc per minor release. - "v#.#.#": expands to latest doc per patch release. - A pair p, which put p.first in the selector, and symlink it to p.second.
9e6a85d
to
6d20ba0
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks great! I think we can merge this. If need be, we can always do some minor adjustments in future PRs.
Eh... failed deployment: https://travis-ci.org/JuliaDocs/Documenter.jl/builds/420718372?utm_source=github_status&utm_medium=notification will push a fix shortly. |
Add
selector
argument tomakedocs
. Theselector
argument decide the content, and order, of the version selector. The argument is a vector, defaulting to["stable", "v#.#", devurl]
where the entriesexpand according to:
"stable"
will point to the latest release."v#.#"
expands to one doc per minor release.devurl
maps to the development docs (Rename latest to dev. #802).The following arguments are also valid to
selector
:"v#"
expands to one doc per major release."v#.#.#"
expands one doc per patch release.p.first
in the selector, and map it top.second
.This lets users opt out of
stable
(#801) if they choose to.