Remove how to contribute with local commands

[Grummfy]

I think, if it's possible, it could be very intresting to add documentation about using this to build docs

[henrykironde]

I agree, there is not enough documentation on this

[humitos]

What do you mean exactly?

These images are used internally by the RTD.org code to build the documentation. It's not something that it's used in a separated way.

[henrykironde]

As a user I expect to see enough information that can enable me replicate what is actually happening when my docs fail to build, or when they build and fail to be deployed.

As a contributor, I expect to be able to follow the instructions and have a good idea, not only the setup of the images, but also some ENV or PATHS to set and more guidelines. I have noticed that the Julia community have lot of docs that do not render on readthedocs, Even when the builds passed successfully.

based on https://github.com/rtfd/readthedocs-docker-images/blob/master/CONTRIBUTING.rst

[humitos]

As a user I expect to see enough information that can enable me replicate what is actually happening when my docs fail to build, or when they build and fail to be deployed.

As a user of readthedocs.org it should be enough with the error message that the build raises in the build page of your project, otherwise I would say that it's a bug in RTD and should be filled in at https://github.com/rtfd/readthedocs.org/issues

As a contributor, I expect to be able to follow the instructions and have a good idea, not only the setup of the images, but also some ENV or PATHS to set and more guidelines. I have noticed that the Julia community have lot of docs that do not render on readthedocs, Even when the builds passed successfully.

If you want to run exactly the same process that readthedocs.org runs, you will need to setup a local installation https://docs.readthedocs.io/en/latest/install.html and import your project to make the build and understand why it is failing exactly.

(there are some attempts to make this easier with a docker-compose file at readthedocs/readthedocs.org#3245 and readthedocs/readthedocs.org#3003 and readthedocs/readthedocs.org#3152)

based on /CONTRIBUTING.rst@master

Following this, specifically the Testing Locally section, what is the error/problem/issue you have?

[Grummfy]

@humitos thanks for your answers, but the readme of this project is a bit confusing. Perhaps, you can update the description like this:

Read the Docs - Docker Images

These are the Docker image definitions used by the Read the Docs build environments to encapsulate the build process.
and put something like this

Read the Docs - Docker Images

These are the Docker image definitions used by the Read the Docs build environments to encapsulate the build process. It's purpose is for internal use. If you whish to have a local or a docker build, follow these instructions
If you want to run exactly the same process that readthedocs.org runs, you will need to setup a local installation https://docs.readthedocs.io/en/latest/install.html and import your project to make the build and understand why it is failing exactly.

(there are some attempts to make this easier with a docker-compose file at readthedocs/readthedocs.org#3245 and readthedocs/readthedocs.org#3003 and readthedocs/readthedocs.org#3152)

or something similar. What do you think? I made a pr with that?

For information, for now I use a docker (umbrellium/sphinx-doc) to build locally, but I would love to see some docker from rtd to have a match with what it will be produce and note an approximation.

[humitos]

Yes, I think we could change the description.

Before that, I would like to have the docker-compose finished or the installation process to be smoother. Otherwise, I think it will finally be more confused/complicated.

Anyway, I would like to know if you follow what Testing Locally says, you get your docs built or not.

[Grummfy]

Thanks, I will try to take some times on it

But honestly I don't really like t build big docker image, I prefer to use them when they are already builded ;)

So I let this open or you prefer to close it?

[humitos]

But honestly I don't really like t build big docker image, I prefer to use them when they are already builded ;)

Well, to contribute with this particular repo, you have you build yours.

If you want to use this image to build your docs (as RTD does) you will probably need to modify a couple of things (because of permission issues -that's what the docker-compose tries to fix with no luck yet)

So I let this open or you prefer to close it?

Leave it open. I think it's still unclear how to contribute :)

[eine]

Anyway, I would like to know if you follow what Testing Locally says, you get your docs built or not.

I does not work for me. I had to slightly modify it in order to install sphinx and sphinx_rtd_theme, as explained in #48. It works, fairly well. I mean, the template is successfully built and I can browse the product, which looks great. However, when I build a 'real' project (say http://ghdl.readthedocs.io) the result I get is slightly different. More precisely, I can see none of the features of RTD itself:

• I had to add :github_url: to the page (as suggested in rtfd/sphinx_rtd_theme#page-level-configuration), in order to have it shown. But the href is not correct.
• The RTD menu and add in the bottom left are not shown.
• The revision short SHA is not shown.

You can see the differences here:

It was built with:

git clone https://github.com/ghdl/ghdl
cd ghdl

docker run --rm -tv /$(pwd):/src readthedocs/build:latest bash -c "\
  pip3 install sphinx recommonmark sphinx_rtd_theme && \
  cd //src/doc && \
  make html"

I believe I am missing some info, such as you adding sphinx in a later stage, because it is hard for me to believe that the base build image used internally by RTD does not require sphinx. Yet, there is nothing about it in https://github.com/rtfd/readthedocs-docker-images/blob/master/Dockerfile

About the RTD menu in the bottom left, I can cope with it. Indeed, I can try to reproduce the multiple version feature. But I'd really like to reproduce what we get at RTD. Note that the objective is to run it in a CI environment, so we don't need multiple project management, access control, or any other of the features offered by RTD as a service.

---

Found it. Sphinx is installed as a dependency of rtfd/readthedocs-build, but the example template project does not include a .readthedocs.yml

[agjohnson]

Unfortunately, I don't think there is a good way for users to test documentation build steps through these images. These images are really only for internal use through RTD, it doesn't make much sense to run this locally for a build. Most of the problems you'll notice in documentation rendering aren't due to these images, but more likely RTD or the overrides that we apply -- or something else in the dependency chain that isn't accounted for while testing between a local instance and RTD.

I think we can clarify that you can only really help debug these images through testing a local RTD instance, or by changing your build image used for your docs. We should update the docs to point to our docs on build.image in our readthedocs.yml file.

[agjohnson]

Duplicate of #48

[westurner]

This seems to work:

• extend FROM readthedocs/build:latest
• preinstall requirements in the image (after COPY)
• mount a volume into $VIRTUAL_ENV/src/venvname (ln -s $WORKON_HOME/venvname)
  • These are paths like virtualenv, virtualenvwrapper, westurner/dotfiles/scripts/venv.py
• YMMV

./docs/Dockerfile:

FROM readthedocs/build:latest

ARG uid=1000
ARG user="user"
ARG home="/home/${user}"
ARG __wrk="${home}/-wrk"
ARG workon_home="${__wrk}/-ve37"
ARG venvname="venvname1"
ARG project="${__wrk}/${venvname}"
ARG virtual_env="${workon_home}/${venvname}"

USER root
RUN useradd ${user} -d ${home} -s /usr/bin/bash -u ${uid} -m

USER ${user}
RUN mkdir -p ${virtual_env} \
    && ln -s ${project} ${virtual_env}/src
VOLUME ${project}

USER 1000

# COPY --chown=${user} \
COPY --chown=1000:1000 \
     requirements.txt requirements_dev.txt ${__wrk}/
RUN python3 -m venv ${virtual_env} \
    && ${virtual_env}/bin/pip install \
    -r ${__wrk}/requirements_dev.txt \
    -r ${__wrk}/requirements.txt

CMD ["/bin/bash"]

./Makefile:

# venv variables *inside the container*
__wrk=${__WRK}
venvname=venvname1
project=${__WRK}/${venvname}
workon_home=${__WRK}/-ve37
virtual_env=${workon_home}/${venvname}
_src=${virtual_env}/src
_wrd=${_src}/${venvname}

dockerimage=${venvname}
dockertag=latest
dockerimagetag=${venvname}:${dockertag}

dockerimagedocs=${venvname}/docs
dockerimagedocstag=${dockerimagedocs}:${dockertag}

DATESTR:=$(shell date +'%Y-%m-%dT%H:%M')
PDFNAME=${venvname}.pdf
PDFNAMEDATE=${venvname}-${DATESTR}.pdf

docker-build-rtdocs:
	cp requirements.txt requirements_dev.txt docs/
	cd docs/ && docker build . -t ${dockerimagedocsname}

docker-run-rtdocs:
	docker run --rm \
		-v "${_SRC}":${project}:z \
		-t ${dockerimagedocstag} bash -c "\
			source ${virtual_env}/bin/activate && \
			cd ${project}/${venvname} && \
			make -C docs html singlehtml latexpdf && \
			ls -la docs/_build docs/_build/latex/${pdfname}"
	@# make html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latexpdf text man texinfo info gettext changes xml pseudoxml linkcheck
	$(MAKE) docs-copy-built

docs-copy-built:
	cd docs/_build && rsync -aAX latex/${PDFNAME} html/_static/${PDFNAMEDATE}
	cd docs/_build/html/_static \
		&& rm ${PDFNAME} \
		&& ln -s ${PDFNAMEDATE} ${PDFNAME}
	rsync -aAX docs/_build/singlehtml docs/_build/html/singlehtml

Build the container and then build the docs in the _build/html directory of the mounted volume:

make docker-build-rtdocs docker-run-rtdocs