Skip to content

Commit

Permalink
Support deployment to the root instead of to a version subfolder, fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
fredrikekre authored Jun 29, 2021
1 parent 87abdcc commit 3d50c1d
Show file tree
Hide file tree
Showing 4 changed files with 77 additions and 25 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

## Version `v0.27.3`

* ![Feature][badge-feature] Documenter can now deploy documentation directly to the "root" instead of versioned folders. ([#1615][github-1615], [#1616][github-1616])

* ![Enhancement][badge-enhancement] The version of Documenter used for generating a document is now displayed in the build information. ([#1609][github-1609], [#1611][github-1611])

* ![Bugfix][badge-bugfix] The HTML front end no longer uses ligatures when displaying code (with JuliaMono). ([#1610][github-1610], [#1617][github-1617])
Expand Down Expand Up @@ -838,6 +840,8 @@
[github-1609]: https://github.com/JuliaDocs/Documenter.jl/pull/1609
[github-1610]: https://github.com/JuliaDocs/Documenter.jl/issues/1610
[github-1611]: https://github.com/JuliaDocs/Documenter.jl/pull/1611
[github-1615]: https://github.com/JuliaDocs/Documenter.jl/issues/1615
[github-1616]: https://github.com/JuliaDocs/Documenter.jl/pull/1616
[github-1617]: https://github.com/JuliaDocs/Documenter.jl/pull/1617

[julia-38079]: https://github.com/JuliaLang/julia/issues/38079
Expand Down
26 changes: 25 additions & 1 deletion docs/src/man/hosting.md
Original file line number Diff line number Diff line change
Expand Up @@ -413,7 +413,12 @@ _This workflow was taken from [CliMA/TimeMachine.jl](https://github.com/CliMA/Ti
## Documentation Versions
The documentation is deployed as follows:
!!! note
This section describes the default mode of deployment, which is by version.
See the following section on [Deploying without the versioning scheme](@ref)
if you want to deploy directly to the "root".
By default the documentation is deployed as follows:
- Documentation built for a tag `vX.Y.Z` will be stored in a folder `vX.Y.Z`.

Expand Down Expand Up @@ -473,6 +478,25 @@ and text of the image can be changed by altering `docs-stable-blue` as described
standard to make it easier for potential users to find documentation links across multiple
package README files.

### Deploying without the versioning scheme

Documenter supports deployment directly to the website root ignoring any version
subfolders as described in the previous section. This can be useful if you use
Documenter for something that is not a versioned project, for example.
To do this, pass `versions = nothing` to the [`deploydocs`](@ref) function.
Now the pages should be found directly at

```
https://USER_NAME.github.io/PACKAGE_NAME.jl/
```

Preview builds are still deployed to the `previews` subfolder.

!!! note
The landing page for the [JuliaDocs GitHub organization](https://juliadocs.github.io)
([source repository](https://github.com/JuliaDocs/juliadocs.github.io)) is one example
where this functionality is used.

---

**Final Remarks**
Expand Down
68 changes: 45 additions & 23 deletions src/Documenter.jl
Original file line number Diff line number Diff line change
Expand Up @@ -409,6 +409,9 @@ the generated html. The following entries are valid in the `versions` vector:
and generate a url from which `"second"` can be accessed.
The second argument can be `"v^"`, to point to the maximum version docs
(as in e.g. `"stable" => "v^"`).
If `versions = nothing` documentation will be deployed directly to the "root", i.e.
not to a versioned subfolder. See the manual section on
[Deploying without the versioning scheme](@ref) for more details.
**`push_preview`** a boolean that specifies if preview documentation should be
deployed from pull requests or not. If your published documentation is hosted
Expand Down Expand Up @@ -481,6 +484,11 @@ function deploydocs(;
deploy_subfolder = deploy_decision.subfolder
deploy_is_preview = deploy_decision.is_preview

# Non-versioned docs: deploy to root
if versions === nothing && !deploy_is_preview
deploy_subfolder = nothing
end

# Add local bin path if needed.
Deps.updatepath!()
# Install dependencies when applicable.
Expand Down Expand Up @@ -585,26 +593,30 @@ function git_push(
end

# Copy docs to `subfolder` directory.
deploy_dir = joinpath(dirname, subfolder)
deploy_dir = subfolder === nothing ? dirname : joinpath(dirname, subfolder)
gitrm_copy(target_dir, deploy_dir)
Writers.HTMLWriter.generate_siteinfo_file(deploy_dir, subfolder)

# Expand the users `versions` vector
entries, symlinks = Writers.HTMLWriter.expand_versions(dirname, versions)

# Create the versions.js file containing a list of `entries`.
# This must always happen after the folder copying.
Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries, symlinks)

# generate the symlinks, make sure we don't overwrite devurl
cd(dirname) do
for kv in symlinks
i = findfirst(x -> x.first == devurl, symlinks)
if i === nothing
rm_and_add_symlink(kv.second, kv.first)
else
throw(ArgumentError(string("link `$(kv)` cannot overwrite ",
"`devurl = $(devurl)` with the same name.")))

if versions !== nothing
# Generate siteinfo-file with DOCUMENTER_CURRENT_VERSION
Writers.HTMLWriter.generate_siteinfo_file(deploy_dir, subfolder)

# Expand the users `versions` vector
entries, symlinks = Writers.HTMLWriter.expand_versions(dirname, versions)

# Create the versions.js file containing a list of `entries`.
# This must always happen after the folder copying.
Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries, symlinks)

# generate the symlinks, make sure we don't overwrite devurl
cd(dirname) do
for kv in symlinks
i = findfirst(x -> x.first == devurl, symlinks)
if i === nothing
rm_and_add_symlink(kv.second, kv.first)
else
throw(ArgumentError(string("link `$(kv)` cannot overwrite ",
"`devurl = $(devurl)` with the same name.")))
end
end
end
end
Expand Down Expand Up @@ -734,12 +746,22 @@ filesystems that are case-insensitive (e.g. on OS X, Windows). Without doing a `
first, `git add -A` will not detect case changes in filenames.
"""
function gitrm_copy(src, dst)
# --ignore-unmatch so that we wouldn't get errors if dst does not exist
run(`git rm -rf --ignore-unmatch $(dst)`)
# git rm also removed parent directories
# Remove individual entries since with versions=nothing the root
# would be removed and we want to preserve previews
if isdir(dst)
for x in filter!(!in((".git", "previews")), readdir(dst))
# --ignore-unmatch so that we wouldn't get errors if dst does not exist
run(`git rm -rf --ignore-unmatch $(joinpath(dst, x))`)
end
end
# git rm also remove parent directories
# if they are empty so need to mkpath after
mkpath(dst)
cp(src, dst; force=true)
# Copy individual entries rather then the full folder since with
# versions=nothing it would replace the root including e.g. the .git folder
for x in readdir(src)
cp(joinpath(src, x), joinpath(dst, x); force=true)
end
end

function getenv(regex::Regex)
Expand Down
4 changes: 3 additions & 1 deletion src/deployconfig.jl
Original file line number Diff line number Diff line change
Expand Up @@ -483,9 +483,11 @@ function post_github_status(type::S, deploydocs_repo::S, sha::S, subfolder=nothi
json["description"] = "Documentation build in progress"
elseif type == "success"
json["description"] = "Documentation build succeeded"
target_url = "https://$(owner).github.io/$(repo)/"
if subfolder !== nothing
json["target_url"] = "https://$(owner).github.io/$(repo)/$(subfolder)/"
target_url *= "$(subfolder)/"
end
json["target_url"] = target_url
elseif type == "error"
json["description"] = "Documentation build errored"
elseif type == "failure"
Expand Down

0 comments on commit 3d50c1d

Please sign in to comment.