8000 Doc build throws an error on pandoc in docker machine · Issue #201 · htcondor/htmap · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Doc build throws an error on pandoc in docker machine #201

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.

Sign up for GitHub

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

Jump to bottom
Closed
stsievert opened this issue Mar 24, 2020 · 6 comments
Closed

Doc build throws an error on pandoc in docker machine #201

stsievert opened this issue Mar 24, 2020 · 6 comments
Labels
bug Something isn't working

Comments

@stsievert
Copy link
Contributor
stsievert commented Mar 24, 2020 •
edited
Loading

Describe the bug
I build the docs with the Docker image (as mentioned in #191 (comment)). This produces an error.

To Reproduce

$ ./dr bash
Building HTMap testing container...
sha256:b329f7172be6c79339a1e265cea798014ba6eb8ec8a13f13d50ccc76bc4fdbd0
Starting HTCondor...
$CondorVersion: 8.8.7 Dec 26 2019 BuildID: Debian-8.8.7-1 PackageID: 8.8.7-1 Debian-8.8.7-1 $
$CondorPlatform: X86_64-Debian_10 $
mapper@f6883da4a08c:~/htmap/docs$
mapper@f6883da4a08c:~/htmap$ pip install -r docs/requirements.txt
# trimmed
mapper@f6883da4a08c:~/htmap$ 
mapper@f6883da4a08c:~/htmap/docs$ pip install -e .
# trimmed
mapper@f6883da4a08c:~/htmap/docs$
mapper@f6883da4a08c:~/htmap$ cd docs
mapper@f6883da4a08c:~/htmap/docs$
mapper@f6883da4a08c:~/htmap$ make html
Running Sphinx v2.4.4
WARNING: logo file 'htmap-logo.svg' does not exist
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://htcondor.readthedocs.io/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 34 source files that are out of date
updating environment: [new config] 34 added, 0 changed, 0 removed
reading sources... [ 52%] tutorials/advanced-mapping
Notebook error:
PandocMissing in tutorials/advanced-mapping.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
http://pandoc.org/installing.html
make: *** [Makefile:20: html] Error 2

Expected behavior
I expect make html to produce HTML files in docs/build/html.

Software Versions:
HTMap is on master; this is from the ./dr bash.

mapper@f6883da4a08c:~/htmap/docs$ python -c "import htcondor, htmap; print(htcondor.version()); print(htmap.version())"
$CondorVersion: 8.8.7 Dec 30 2019 BuildID: UW_Python_Wheel_Build $
HTMap version 0.5.1
mapper@f6883da4a08c:~/htmap/docs$ condor_version
$CondorVersion: 8.8.7 Dec 26 2019 BuildID: Debian-8.8.7-1 PackageID: 8.8.7-1 Debian-8.8.7-1 $
$CondorPlatform: X86_64-Debian_10 $
mapper@f6883da4a08c:~/htmap/docs$ cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 10 (buster)"
NAME="Debian GNU/Linux"
VERSION_ID="10"
VERSION="10 (buster)"
VERSION_CODENAME=buster
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"
mapper@f6883da4a08c:~/htmap/docs$
mapper@f6883da4a08c:~/htmap/docs$ cat /proc/version
Linux version 4.19.76-linuxkit (root@d203b39a3d78) (gcc version 8.3.0 (Alpine 8.3.0)) #1 SMP Thu Oct 17 19:31:58 UTC 2019
mapper@f6883da4a08c:~/htmap/docs$

Screenshots
If applicable, add screenshots to help explain your problem.

Additional context
Add any other context about the problem here.
@stsievert stsievert added the bug Something isn't working label Mar 24, 2020
@stsievert
Copy link
Contributor Author

Additionally, the documentation at https://htmap.readthedocs.io/en/latest/devs/env.html#building-the-docs is out of date.

@JoshKarpel
Copy link
Contributor

Ah, dependency management, my old nemesis...

I think those instructions will work as long as you can actually do a bare-metal install of HTMap on your machine, which is really only convenient on Linux. For non-Linux users, I'd like to provide a Dockerfile and associated run script which "does the right" thing, which in my mind means serving up the docs via sphinx-autobuild from a port inside the container, with a bind-mount back to the source so you can edit live. Does that sound like a good solution to you @stsievert ?

@stsievert
Copy link
Contributor Author

I think those instructions will work as long as you can actually do a bare-metal install of HTMap on your machine, which is really only convenient on Linux.

I was in the Docker machine (the first line is ./dr bash). Shouldn't that work? I tried installing pandoc as the root user (/bin/su; apt install pandoc) but that failed because I didn't know the root password.

For non-Linux users, I'd like to provide a Dockerfile and associated run script which "does the right" thing, which in my mind means serving up the docs via sphinx-autobuild from a port inside the container, with a bind-mount back to the source so you can edit live.

I'd prefer to get ./dr bash working. That's a lot cleaner. That makes running the tests easy and clear for developers, and they can refer to the sphinx docs for building the documentation.

@JoshKarpel
Copy link
Contributor

I think those instructions will work as long as you can actually do a bare-metal install of HTMap on your machine, which is really only convenient on Linux.

I was in the Docker machine (the first line is ./dr bash). Shouldn't that work? I tried installing pandoc as the root user (/bin/su; apt install pandoc) but that failed because I didn't know the root password.

There's a root user in the container, but no way to become them or use sudo. So, not unexpected - pandoc would have to be installed in the container build.

For non-Linux users, I'd like to provide a Dockerfile and associated run script which "does the right" thing, which in my mind means serving up the docs via sphinx-autobuild from a port inside the container, with a bind-mount back to the source so you can edit live.

I'd prefer to get ./dr bash working. That's a lot cleaner. That makes running the tests easy and clear for developers, and they can refer to the sphinx docs for building the documentation.

I guess I was thinking of of this in terms of keeping the test container clean, but it's pretty messy anyway, and I like the idea of providing a single entrypoint for "working on HTMap".

@stsievert stsievert mentioned this issue Mar 24, 2020
Merged
JoshKarpel added a commit that referenced this issue Mar 25, 2020
@JoshKarpel
revise dev environment setup and corresponding instructions (resolve #…
f3c6f03 
…201)
@JoshKarpel
Copy link
Contributor

@stsievert branch v0.6.0 now has commit f3c6f03 , which revises the dev environment to make sure both tests and docs run in the dev container and updates the documentation appropriately. Please give it a try and let me know what you think!

@stsievert
Copy link
Contributor Author

Yup, both approaches worked for me:

$ ./dr bash
# ...
mapper@dfa0e19cf84e:~/htmap/docs$ make html
# completed successfully

I have some documentation improvements in #202.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug Something isn't working
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@stsievert @JoshKarpel
0