Add selector argument to deploydocs #813

fredrikekre · 2018-08-20T20:45:08Z

Add selector argument to makedocs. The selector argument decide the content, and order, of the version selector. The argument is a vector, defaulting to ["stable", "v#.#", devurl] where the entries
expand 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.
A string which directly maps to a folder.
A pair, which will put p.first in the selector, and map it to p.second.

This lets users opt out of stable (#801) if they choose to.

fredrikekre · 2018-08-20T21:19:31Z

src/Documenter.jl

-                        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


Note to self: This should be removed.

fredrikekre · 2018-08-20T21:34:39Z

Succesful deploy here: https://fredrikekre.github.io/Literate.jl/v1/ with this: https://github.com/fredrikekre/Literate.jl/blob/6b9dd249cfbc4d19f96e961c525d83568adb50dd/docs/make.jl#L62

fredrikekre · 2018-08-20T22:30:37Z

src/Documenter.jl

+
+                # generate the symlinks
+                cd(dirname) do
+                    foreach(kv -> symlink(kv.second, kv.first), symlinks)


Need to remove existing links here. And I guess error if what exist there is not an old symlink?

fredrikekre · 2018-08-21T07:18:39Z

Ok, things seem to work now, so this should be ready for review.

mortenpi

A few tiny things, but this looks great overall!

mortenpi · 2018-08-22T10:35:27Z

src/Writers/HTMLWriter.jl


+# write version file
+function generate_version_file(dir::AbstractString, selector_entries)


Since we're not using the directory as such here anymore, maybe we should change the argument to be the filename?

mortenpi · 2018-08-22T10:48:34Z

src/Documenter.jl

+ - `"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"`.


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"?

mortenpi · 2018-08-22T10:50:50Z

src/Documenter.jl

@@ -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.


How would you change the name of the stable/ directory? "new-name" => "stable"?

Hmm, maybe introduce a token like "v^.^.^" to indicate maximum version, and the default here could be "stable" => "v^.^.^" ?

mortenpi · 2018-08-22T10:52:04Z

src/Documenter.jl

+ - `"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.


Maybe better to say "includes links to the latest version for major/minor version"?

mortenpi · 2018-08-22T10:59:28Z

test/htmlwriter.jl

+        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


What is the difference of the directories with and without v?

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

fredrikekre · 2018-08-22T13:59:01Z

Thanks for the review. I pushed a much simplified (?) version. Now only the following things are allowed:

"v#" one per major version
"v#.#" one per minor version
"v#.#.#" one per patch
"v^" the latest version
"first" => "second" mapping first to second, with special-casing when second is "v^", to be able to do e.g. "stable" => "v^"

Thus, removed the special casing of "stable", and also removed the string only (replacing "dev" with "dev" => "dev")

mortenpi · 2018-08-23T09:47:03Z

src/Documenter.jl

@@ -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:


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.

I like versions.

mortenpi · 2018-08-23T09:49:09Z

src/Documenter.jl

+ - `"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.


What does it put in the selector though? Or can you just use this in a pair?

It will put vX.Y for latest X and Y, and symlink to vX.Y.Z for latest Z.

mortenpi · 2018-08-23T09:50:30Z

src/Documenter.jl

+ - `"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^"`).


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.

fredrikekre · 2018-08-23T22:24:29Z

I changed selector -> versions, and tried to explain a bit more with the links. However, I think that we should explain it better, but maybe in the manual and not the docstring, so could be part of a future doc-PR.

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.

mortenpi

This looks great! I think we can merge this. If need be, we can always do some minor adjustments in future PRs.

fredrikekre · 2018-08-26T13:40:47Z

Eh... failed deployment: https://travis-ci.org/JuliaDocs/Documenter.jl/builds/420718372?utm_source=github_status&utm_medium=notification will push a fix shortly.

fredrikekre added the Type: Enhancement label Aug 20, 2018

fredrikekre added this to the 0.20.0 milestone Aug 20, 2018

fredrikekre requested a review from mortenpi August 20, 2018 20:45

fredrikekre changed the title ~~Add selector argument to makedocs~~ Add selector argument to deploydocs Aug 20, 2018

fredrikekre force-pushed the fe/selector branch from 5f04725 to 8ce2d6d Compare August 20, 2018 21:14

fredrikekre commented Aug 20, 2018

View reviewed changes

fredrikekre force-pushed the fe/selector branch from 8ce2d6d to 04d6def Compare August 20, 2018 22:08

fredrikekre commented Aug 20, 2018

View reviewed changes

fredrikekre force-pushed the fe/selector branch 2 times, most recently from 3da546e to 1a622e6 Compare August 21, 2018 07:16

fredrikekre force-pushed the fe/selector branch from 1a622e6 to 526489b Compare August 21, 2018 07:26

mortenpi mentioned this pull request Aug 21, 2018

Breaking release #713

Closed

11 tasks

mortenpi reviewed Aug 22, 2018

View reviewed changes

fredrikekre force-pushed the fe/selector branch from 526489b to 297c30d Compare August 22, 2018 13:55

fredrikekre mentioned this pull request Aug 23, 2018

Changes to docs deployment conventions JuliaLang/julia#26825

Closed

mortenpi reviewed Aug 23, 2018

View reviewed changes

fredrikekre force-pushed the fe/selector branch from 297c30d to 9e6a85d Compare August 23, 2018 22:17

fredrikekre force-pushed the fe/selector branch from 9e6a85d to 6d20ba0 Compare August 24, 2018 06:08

mortenpi approved these changes Aug 26, 2018

View reviewed changes

fredrikekre merged commit 332cd3f into master Aug 26, 2018

fredrikekre deleted the fe/selector branch August 26, 2018 10:16

fredrikekre added a commit that referenced this pull request Aug 26, 2018

Fix bug from #813.

e5a4294

fredrikekre added a commit that referenced this pull request Aug 26, 2018

Fix bug from #813. (#817)

58e1883

fredrikekre mentioned this pull request Aug 26, 2018

Fix bug from #813. #817

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add selector argument to deploydocs #813

Add selector argument to deploydocs #813

fredrikekre commented Aug 20, 2018 •

edited

Loading

fredrikekre Aug 20, 2018

fredrikekre commented Aug 20, 2018

fredrikekre Aug 20, 2018

fredrikekre commented Aug 21, 2018

mortenpi left a comment

mortenpi Aug 22, 2018

mortenpi Aug 22, 2018

mortenpi Aug 22, 2018

fredrikekre Aug 22, 2018

mortenpi Aug 22, 2018

mortenpi Aug 22, 2018

fredrikekre Aug 22, 2018

fredrikekre commented Aug 22, 2018

mortenpi Aug 23, 2018

fredrikekre Aug 23, 2018

mortenpi Aug 23, 2018

fredrikekre Aug 23, 2018

mortenpi Aug 23, 2018

fredrikekre commented Aug 23, 2018

mortenpi left a comment

fredrikekre commented Aug 26, 2018


		# write version file
		function generate_version_file(dir::AbstractString, selector_entries)

Add selector argument to deploydocs #813

Add selector argument to deploydocs #813

Conversation

fredrikekre commented Aug 20, 2018 • edited Loading

Choose a reason for hiding this comment

fredrikekre commented Aug 20, 2018

Choose a reason for hiding this comment

fredrikekre commented Aug 21, 2018

mortenpi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fredrikekre commented Aug 22, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fredrikekre commented Aug 23, 2018

mortenpi left a comment

Choose a reason for hiding this comment

fredrikekre commented Aug 26, 2018

fredrikekre commented Aug 20, 2018 •

edited

Loading