An old side-project was using an out-of-date version of IdentityServer4 (2.0.0). The project was mainly a learning project, so before jumping to the latest, I wanted to see what changed between 2.0.0 and 2.5.4.
Unfortunately, the documentation at https://identityserver4.readthedocs.io/ didn't have anything from the version 2 days. So I decided to build them myself in docker.
Building the docs in docker
IdentityServer uses "Read the Docs", which is built with Sphinx document generator. To make things slightly simpler, there are already Sphinx docker images up on docker Hub. Even better, they include instructions on how to mount a volume and perform a build. So I tried it.
First things first, cloning the repo and checkout out the version I wanted to build:
git clone https://github.com/IdentityServer/IdentityServer4.git cd IdentityServer4 git checkout tags/2.5.4 -b tag_2_5_4
Taking the command directly from docker hub I hit a snag:
docker run --rm -v C:\Play\Repos\IdentityServer4\docs:/docs sphinxdoc/sphinx make html Running Sphinx v3.2.1 Configuration error: There is a programmable error in your configuration file: Traceback (most recent call last): File "/usr/local/lib/python3.8/site-packages/sphinx/config.py", line 319, in eval_config_file execfile_(filename, namespace) File "/usr/local/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 89, in execfile_ exec(code, _globals) File "/docs/conf.py", line 139, in <module> import sphinx_rtd_theme ModuleNotFoundError: No module named 'sphinx_rtd_theme' make: *** [Makefile:53: html] Error 2
As you can see from the highlighted line above, the image was missing a module needed. That type of thing must happen a lot, as the docker hub site includes a "tips" section on how to build your own image.
Building your own image
Following the tip, I created a Dockerfile with the following contents:
FROM sphinxdoc/sphinx WORKDIR /docs RUN pip install sphinx_rtd_theme
Built my image:
docker build -t "sphinxdocs" .
And ran the same command, but this time with my image:
docker run --rm -v C:\Play\Repos\IdentityServer4\docs:/docs sphinxdocs make html
I won't include all the output as it's long, but once that's finished, you should have a
_build\html\index.html file in the
docs directory containing the IdentityServer documentation as per 2.5.4.