Skip to content
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

Remove Travis.genkeys and Documenter.generate #789

Merged
merged 5 commits into from
Aug 16, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,6 @@ notifications:
email: false

after_success:
- julia -e 'cd(Pkg.dir("Documenter", "test")); include("coverage.jl")'
- julia --project=docs -e 'using Pkg; Pkg.instantiate()'
- julia --project=docs docs/make.jl
- julia -e 'cd("test"); include("coverage.jl")'
106 changes: 106 additions & 0 deletions docs/Manifest.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
[[Base64]]
uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"

[[Compat]]
deps = ["Base64", "Dates", "DelimitedFiles", "Distributed", "InteractiveUtils", "LibGit2", "Libdl", "LinearAlgebra", "Markdown", "Mmap", "Pkg", "Printf", "REPL", "Random", "Serialization", "SharedArrays", "Sockets", "SparseArrays", "Statistics", "Test", "UUIDs", "Unicode"]
git-tree-sha1 = "277d3807440d9793421354b6680911fc95d91a84"
uuid = "34da2185-b29b-5c13-b0c7-acf172513d20"
version = "1.0.1"

[[Dates]]
deps = ["Printf"]
uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"

[[DelimitedFiles]]
deps = ["Mmap"]
uuid = "8bb1440f-4735-579b-a4ab-409b98df4dab"

[[Distributed]]
deps = ["LinearAlgebra", "Random", "Serialization", "Sockets"]
uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"

[[DocStringExtensions]]
deps = ["Compat"]
git-tree-sha1 = "a2ab006ff561a57eb858cee5314445b16c2fd2dd"
uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
version = "0.4.6"

[[DocumenterTools]]
deps = ["DocStringExtensions", "LibGit2"]
git-tree-sha1 = "b28c164f4c5389cf5c111de4c2bec5541e6d5323"
repo-rev = "master"
repo-url = "https://github.com/JuliaDocs/DocumenterTools.jl"
uuid = "46bb7b6e-9a58-11e8-21f8-9f2f45a0fcba"
version = "0.0.0"

[[InteractiveUtils]]
deps = ["LinearAlgebra", "Markdown"]
uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"

[[LibGit2]]
uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"

[[Libdl]]
uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"

[[LinearAlgebra]]
deps = ["Libdl"]
uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

[[Logging]]
uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"

[[Markdown]]
deps = ["Base64"]
uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"

[[Mmap]]
uuid = "a63ad114-7e13-5084-954f-fe012c677804"

[[Pkg]]
deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"

[[Printf]]
deps = ["Unicode"]
uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"

[[REPL]]
deps = ["InteractiveUtils", "Markdown", "Sockets"]
uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"

[[Random]]
deps = ["Serialization"]
uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

[[SHA]]
uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"

[[Serialization]]
uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"

[[SharedArrays]]
deps = ["Distributed", "Mmap", "Random", "Serialization"]
uuid = "1a1011a3-84de-559e-8e89-a11a2f7dc383"

[[Sockets]]
uuid = "6462fe0b-24de-5631-8697-dd941f90decc"

[[SparseArrays]]
deps = ["LinearAlgebra", "Random"]
uuid = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"

[[Statistics]]
deps = ["LinearAlgebra", "SparseArrays"]
uuid = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"

[[Test]]
deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[[UUIDs]]
deps = ["Random"]
uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"

[[Unicode]]
uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
2 changes: 2 additions & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
[deps]
DocumenterTools = "46bb7b6e-9a58-11e8-21f8-9f2f45a0fcba"
6 changes: 3 additions & 3 deletions docs/make.jl
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
using Documenter
using Documenter, DocumenterTools

makedocs(
modules = [Documenter],
modules = [Documenter, DocumenterTools],
clean = false,
format = :html,
assets = ["assets/favicon.ico"],
Expand Down Expand Up @@ -51,7 +51,7 @@ makedocs(
deploydocs(
repo = "github.com/JuliaDocs/Documenter.jl.git",
target = "build",
julia = "nightly",
julia = "1.0",
deps = nothing,
make = nothing,
)
10 changes: 7 additions & 3 deletions docs/src/lib/public.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,13 @@ Documenter
makedocs
hide
deploydocs
Documenter.generate
Travis
Travis.genkeys
Deps
Deps.pip
```

## DocumenterTools

```@docs
DocumenterTools.generate
DocumenterTools.Travis.genkeys
```
13 changes: 8 additions & 5 deletions docs/src/man/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,12 @@

## Installation

Documenter is a registered package and so can be installed via `Pkg.add`.
Documenter can be installed using the Julia package manager.
From the Julia REPL, type `]` to enter the Pkg REPL mode and run

```julia
Pkg.add("Documenter")
```

This package supports Julia `0.6` and `0.7-dev`.
pkg> add Documenter
```

## Usage

Expand All @@ -18,6 +17,10 @@ to creating a simple document.

### Setting up the folder structure

!!! note
The function [`DocumenterTools.generate`](@ref) from the `DocumenterTools` package
can generate the basic structure that Documenters expects.

Firstly, we need a Julia module to document. This could be a package generated via
`PkgDev.generate` or a single `.jl` script accessible via Julia's `LOAD_PATH`. For this
guide we'll be using a package called `Example.jl` that has the following directory layout:
Expand Down
10 changes: 7 additions & 3 deletions docs/src/man/hosting.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,10 +41,14 @@ Deploy keys provide push access to a *single* repository, to allow secure deploy
They are `which`, `git`, and `ssh-keygen`. Make sure these are installed before you
begin this section.

Open a Julia REPL and import [`Documenter`](@ref).
SSH keys can be generated with the `Travis.genkeys` from the `DocumenterTools` package.
Install and load it as

```
pkg> add DocumenterTools
```
```jlcon
julia> using Documenter
julia> using DocumenterTools
```

Then call the [`Travis.genkeys`](@ref) function as follows:
Expand Down Expand Up @@ -119,7 +123,7 @@ Add the following at the end of the file:
```julia
deploydocs(
repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git",
julia = "0.6"
julia = "1.0"
)
```

Expand Down
10 changes: 10 additions & 0 deletions src/DocChecks.jl
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ for checking docs.
module DocChecks

import ..Documenter:
Documenter,
Documents,
Utilities

Expand Down Expand Up @@ -83,7 +84,11 @@ sigs(::Any) = Type[Union{}]

# Footnote checks.
# ----------------
"""
$(SIGNATURES)
Checks footnote links in a [`Documents.Document`](@ref).
"""
function footnotes(doc::Documents.Document)
println(" > checking footnote links.")
# A mapping of footnote ids to a tuple counter of how many footnote references and
Expand Down Expand Up @@ -143,6 +148,11 @@ footnote(other, orphans::Dict) = true

hascurl() = (try; success(`curl --version`); catch err; false; end)

"""
$(SIGNATURES)
Checks external links using curl.
"""
function linkcheck(doc::Documents.Document)
if doc.user.linkcheck
if hascurl()
Expand Down
96 changes: 2 additions & 94 deletions src/Documenter.jl
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,6 @@ Two functions are exported from this module for public use:
- [`makedocs`](@ref). Generates documentation from docstrings and templated markdown files.
- [`deploydocs`](@ref). Deploys generated documentation from *Travis-CI* to *GitHub Pages*.
Additionally it provides the unexported [`Documenter.generate`](@ref), which can be used to
generate documentation stubs for new packages.
$(EXPORTS)
"""
Expand All @@ -34,15 +31,14 @@ include("DocChecks.jl")
include("Writers/Writers.jl")
include("Deps.jl")
include("Generator.jl")
include("Travis.jl")

import .Utilities: Selectors


# User Interface.
# ---------------

export Travis, Deps, makedocs, deploydocs, hide
export Deps, makedocs, deploydocs, hide

"""
makedocs(
Expand Down Expand Up @@ -591,92 +587,4 @@ function getenv(regex::Regex)
error("could not find key/iv pair.")
end

"""
$(SIGNATURES)
Creates a documentation stub for a package called `pkgname`. The location of
the documentation is assumed to be `<package directory>/docs`, but this can
be overriden with the keyword argument `dir`.
It creates the following files
```
docs/
.gitignore
src/index.md
make.jl
mkdocs.yml
```
# Arguments
**`pkgname`** is the name of the package (without `.jl`). It is used to
determine the location of the documentation if `dir` is not provided.
# Keywords
**`dir`** defines the directory where the documentation will be generated.
It defaults to `<package directory>/docs`. The directory must not exist.
# Examples
```jlcon
julia> using Documenter
julia> Documenter.generate("MyPackageName")
[ ... output ... ]
```
"""
function generate(pkgname::AbstractString; dir=nothing)
# TODO:
# - set up deployment to `gh-pages`
# - fetch url and username automatically (e.g from git remote.origin.url)

# Check the validity of the package name
if length(pkgname) == 0
error("Package name can not be an empty string.")
end
# Determine the root directory where we wish to generate the docs and
# check that it is a valid directory.
docroot = if dir === nothing
pkgdir = Pkg.dir(pkgname)
if !isdir(pkgdir)
error("Unable to find package $(pkgname).jl at $(pkgdir).")
end
joinpath(pkgdir, "docs")
else
dir
end

if ispath(docroot)
error("Directory $(docroot) already exists.")
end

# deploy the stub
try
@info("Deploying documentation to $(docroot)")
mkdir(docroot)

# create the root doc files
Generator.savefile(docroot, ".gitignore") do io
write(io, Generator.gitignore())
end
Generator.savefile(docroot, "make.jl") do io
write(io, Generator.make(pkgname))
end
Generator.savefile(docroot, "mkdocs.yml") do io
write(io, Generator.mkdocs(pkgname))
end

# Create the default documentation source files
Generator.savefile(docroot, "src/index.md") do io
write(io, Generator.index(pkgname))
end
catch
rm(docroot, recursive=true)
rethrow()
end
nothing
end

end
end # module
Loading