Steamline hosting documentation #144
Comments
|
Yes, we can certainly improve parts of that page if they're not clear enough. Could you describe which parts in particular weren't clear, since that'll help with figuring out what wording to change. Which steps did you get stuck on? |
|
Hmm, I just tried a few hours ago and it took me a while to figure out how to install command line travis on Windows. First I had to install Ruby, and then I had to use Ruby's package manager to install travis. Then when I tried to rerun make.jl, I got an error like "ERROR: LoadError: stat: operation not permitted (EPERM)". I could have spent some more trying to figure out what was going wrong, but at that point I realized I hadn't even made it through the first of eight sections so I decided to give up. I'm not sure better documentation can help when the process itself seems overly involved. |
Yeah, I've not tried any of this on Windows, so it's not too surprising that it's a bit more difficult there. I think there may be a way to do the travis upload step manually, so I can try look into that — it would be great to not have to install all that extra stuff.
If you could recreate that error and post the complete backtrace that would be great. Definitely shouldn't be throwing ugly errors like that. |
|
Here is the code pkgname = "ChainMap"
indexstring = """
using Documenter, $pkgname
makedocs()
"""
makestring = """
# $pkgname.jl Documentation
```@autodocs
Modules = [$pkgname]
\```
"""
mkpath("docs/src")
write("docs/make.jl", indexstring)
write("docs/src/index.md", makestring)
run(`julia docs/make.jl`)This seems to work once or maybe twice and then stop working. The backslash isn't in the original (I bet there's a real escape sequence). My traceback is currently |
|
Continuing on: I'm trying to run In Atom I get this error: In the REPL I get a key output, but then I would continue trying to add my key to the repository, but I don't see any instructions displayed? |
|
P.S. I can't figure out how to install command line which for Windows. ssh-keygen seems to have come with git but I have to add it to my path |
Does just running
I've come across those before, unrelated to Documenter, when packages are installed on a network drive. Is your package local or on a network folder?
Perhaps run all the commands in a normal Julia terminal rather than through Atom's terminal just so we can avoid possible interference from there.
The diff --git a/src/Documenter.jl b/src/Documenter.jl
index 91b5111..27fb6bd 100644
--- a/src/Documenter.jl
+++ b/src/Documenter.jl
@@ -431,10 +431,10 @@ following command lines programs to be installed:
function genkeys(package)
# Error checking. Do the required programs exist?
isdir(Pkg.dir(package)) || error("'$package' could not be found in '$(Pkg.dir())'.")
- success(`which which`) || error("'which' not found.")
- success(`which git`) || error("'git' not found.")
- success(`which travis`) || error("'travis' not found.")
- success(`which ssh-keygen`) || error("'ssh-keygen' not found.")
+ # success(`which which`) || error("'which' not found.")
+ # success(`which git`) || error("'git' not found.")
+ # success(`which travis`) || error("'travis' not found.")
+ # success(`which ssh-keygen`) || error("'ssh-keygen' not found.")
directory = "docs"
filename = ".documenter" |
|
No, everything is local. Running make.jl from within doc does work. Commenting out the which lines seems to have helped atom out, but it freezes as a y/n question (.documenter already exists, do you want to replace it). I tried adding ssh-keygen to my path (which is hiding in C:\Program Files\Git\usr\bin) but I'm still getting the same error in the repl. |
Presumably
Not sure if Atom has implemented user input in it's terminal. That's probably why it froze. Just use the normal Julia terminal instead.
What steps did you take to add |
|
ssh-keygen is correctly in my path. It's in system properties, the advanced tab, then click the environmental variables... button. I finally got Travis.genkeys to work by following through the command line code manually. The auto login does not seemed to have worked: I still had to enter my github credentials. |
|
PS the which command-line tool is also packaged with git in the same folder that ssh-keygen is. |
For the
So in Julia's shell mode neither of those are available, but are on your path? Probably an upstream issue and not related to Documenter then I'd assume. I'll see if I can set up a Windows VM sometime next week perhaps and see if I can work out what's happening myself. |
|
I think I'm getting closer. I've put together all the changes I've attempted to make into a single function. This kind of model (one function to do everything) is what I was hoping for. function defaultdocumentation(PACKAGE_NAME, USER_NAME)
cd(Pkg.dir(PACKAGE_NAME))
indexstring = """
using Documenter, $PACKAGE_NAME
makedocs(
modules = $PACKAGE_NAME
)
deploydocs(
repo = "github.com/$USER_NAME/$PACKAGE_NAME.jl.git"
deps = Deps.pip("pygments", "mkdocs", "mkdocs-material", "python-markdown-math")
)
"""
makestring = """
# $PACKAGE_NAME.jl Documentation
```@index
\```
```@autodocs
Modules = [$PACKAGE_NAME]
\```
"""
traviscode = """
- julia -e 'Pkg.add("Documenter")'
- julia -e 'cd(Pkg.dir("$PACKAGE_NAME")); include(joinpath("docs", "make.jl"))'
"""
mkdocscode = """
site_name: $PACKAGE_NAME.jl
repo_url: https://github.com/$USER_NAME/$PACKAGE_NAME.jl
site_author: $USER_NAME
theme: readthedocs
extra:
palette:
primary: 'indigo'
accent: 'blue'
extra_css:
- assets/Documenter.css
extra_javascript:
- https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML
- assets/mathjaxhelper.js
markdown_extensions:
- codehilite
- extra
- tables
- fenced_code
- mdx_math
docs_dir: 'build'
pages:
- Home: index.md
"""
gitignorecode =
"""
docs/build/
docs/site/
"""
readmecode = [
"[](https://$USER_NAME.github.io/$PACKAGE_NAME.jl/stable)\n"
"[](https://$USER_NAME.github.io/$PACKAGE_NAME.jl/latest)\n"
]
mkpath("docs/src")
write("docs/make.jl", indexstring)
write("docs/src/index.md", makestring)
open(".travis.yml","a") do x
write(x, traviscode)
end
open(".gitignore","a") do x
write(x, gitignorecode)
end
# I bet there's a better way to insert into the third line of a file
readmeexisting = readlines("README.md")
output = [readmeexisting[1:2]; readmecode; readmeexisting[3:end]]
write("README.md", output)
end |
This is kind of what |
|
In travis, under all four builds, I'm getting "skipping docs deployment". It looks like that could happen for any number of reasons. Would it be possible for documenter to also list a reason why (or a list of reasons why) it's skipping deployment? |
|
You can set the From looking at the ChainMap.jl repo here's a few things that might be help:
|
|
Ok, I must of messed up everything when I tried to do it manually. So I'm trying to get I ran
I've poked around on the internet for a fix. People are saying to making sure AddTrustExternalCARoot-2048.pem is in my C:\Ruby22-x64\lib\ruby\2.2.0\rubygems\ssl_certs folder, and I've checked and it is. |
|
How did you install (Note that there's also the alternative route for giving Travis push access to the needed repo, using the |
|
Ok, well, that second method seems to have worked. But now I'm getting another error: (MH: edited formatting) |
Those are additional plugins for (Does |
|
It took me a while to get mkdocs up and running as well; downloading python, adding pip to my path (which came with the version of python I downloaded), downloading mkdocs with pip, figuring out the syntax to mkdocs... Well I got at least a latest version of the docs up and running. It's only a list of docstrings at the moment. I decided that I wanted to move my tests to the examples in the docstrings. That meant that the coverage statistics weren't working for me. Anyway, I wrote a short script to put all the code in the examples in my docstrings into my function doclines(filein)
text = readlines(filein)
starts = map(_ -> ismatch(r"```.+", chomp(_) ), text)
ends = map(_ -> chomp(_) == "```", text)
Test.@test sum(starts) == sum(ends)
withbounds = text[cumsum(starts) - cumsum(ends) .== 1]
withoutbounds = filter(x -> !startswith(x, "```"), withbounds)
backslash_removed = map(x -> replace(x, r"\\", ""), withoutbounds)
end
lines = ["using ChainMap\n\n"
doclines(joinpath(Pkg.dir("ChainMap", "src", "doc.jl")));
doclines(joinpath(Pkg.dir("ChainMap", "README.md")))]
write(joinpath(Pkg.dir("ChainMap"), "test", "runtests.jl"),
lines) |
Yeah, it can be a bit of a pain. We'll be adding some HTML output soonish so that you don't need mkdocs at all.
What could work is running include(joinpath("..", "docs", "make.jl"))to your At the moment even if there's doctest errors |
|
Hey, so I finally went back and fixed my tests so all that's there is makedocs(strict = true). I'm running into an issue now where on 0.5 a bunch of doctests are failing because of extraneous warnings: |
|
Since those kind of warnings seem to usually only show up the first time some code is run you could probably run the code that causes them some time prior to the doctests, perhaps in |
|
I'm not sure I understand. I tried duplicating the doctest call; first with strict = false then with strict = true, and it didn't seem to have helped. |
|
Solved with putting |
|
To avoid the warnings what I mean is: So the first call to using Documenter, ChainMap
_ = [1, -1]
@over abs
makedocs(strict = true)which should silence the warnings within the actual docstrings hopefully. |
I've tried to follow through the steps in the hosting documentation section twice now and I've gotten stuck both times. I wonder if there would be a way to streamline some (or all) of the steps? Something like
hostdocs()? Either that, or updatePkg.generate()to automatically include some (or all) of the necessary infrastructure?The text was updated successfully, but these errors were encountered: