Open tdene opened 2 years ago
In retrospect, this is a silly suggestion. BTD is designed to work with pre-built Docker images, not install new packages.
That said, I am having difficulty using the btdi/pandoc
image. It appears to not have pip installed.
@tdene, you can build a custom image right before using the Action. See, for instance:
Image ghdl/doc
does not exist in any public registry. It is built in one step and used in another step.
Please, try that approach in your repository, to find which specific system packages you are missing in image btdi/pandoc. Then, either post here or open a PR to suggest adding them to the dockerfile in this repo.
The "btdi" dockerfiles are located in the buildthedocs/containers repo. See https://github.com/buildthedocs/containers/blob/main/texlive.dockerfile.
I'm sorry, I still don't understand how the config file is meant to be used.
My .btd.yml
file is the following:
input: docs
output: _build
requirements: requirements.txt
target: gh-pages
formats: [ html ]
images:
html: btdi/pandoc
theme: https://codeload.github.com/buildthedocs/sphinx.theme/tar.gz/v1
The relevant section is the images
part. I would like the docs
folder in my repository to compile HTML docs, for which purpose pandoc is required. I thought that html: btdi/pandoc
was the argument I needed to add, but it does not seem to be changing anything.
My other attempt has been to fork this repository and overwrite Dockerfile
. Changing FROM
to btdi/pandoc
fails due to pip not being included in the pandoc docker image.. Modifying the Dockerfile to use the default btdi/btd
image and attempting to install pandoc afterwards seems to work, although it is dreadfully slow and convoluted due to btdi/btd
being based on Alpine, whose apk
package manager does not have pandoc, meaning that it has to be compiled via cabal
.
Regardless, forking the repository and modifying the Dockerfile very much seems like the wrong approach here.
Would you mind helping me figure out how to approach this problem through the config file, or giving me some pointers for how to look through the source code for a solution?
Alright, sorry. There was a lot of confusion on my part about how this tool worked.
I've looked through the source code, I've debugged, I understand what's going on.
The only issue that exists is that the sphinx:featured
docker image does not include pandoc
, which Sphinx uses to handle ipynb notebooks. I believe everything else in this issue is irrelevant.
As I eventually found out, pandoc can be installed on Alpine by adding http://dl-cdn.alpinelinux.org/alpine/edge/testing/
to /etc/apk/repositories
. A simple apk add pandoc
is sufficient at that point. I would like to suggest that the Sphinx docker image is updated to install pandoc in this fashion.
This issue may be closed.
BTD provides a method of specifying Python package requirements via the
requirements
field in.btd.yml
.As far as I can tell, BTD does not provide a method of specifying system package requirements.
This is relevant due to
pandoc
, whose Python package merely provides bindings to the system package. In order to usepandoc
, it must be installed via bothpip
as well as the system package manager.An example may be found here.