GDAL doc build on Windows

environment.yml

name: gdal-docs
channels:
  - conda-forge
dependencies:
  - doxygen
  - gdal
  - pip
  - pip:
    - breathe
    - numpy
    - recommonmark
    - sphinx
    - sphinx-bootstrap-theme
    - sphinx-markdown-tables
    - sphinx-rtd-theme
    - sphinxcontrib-bibtex
    - sphinxcontrib-jquery
    - sphinxcontrib-spelling
    - pyenchant
    - myst_nb

terminal.md

Short of going through and providing a full Windows config for the Cmake configuration, I was able to get the following to work.

After cloning GDAL, change to the doc directory.

cd /path/to/gdal/doc

Next step does assume that Python is installed.

python source\build_driver_summary.py source\drivers\raster raster_driver_summary source\drivers\raster\driver_summary.rst
python source\build_driver_summary.py source\drivers\vector vector_driver_summary source\drivers\vector\driver_summary.rst

Now we will setup the suggested GDAL doc environment. I have lightly modified the environment.yml, see the update in this gist.

mamba env create -f environment.yml
mamba activate gdal-docs

Now, we will manually run some Doxygen commands for now.

mkdir build\xml
(
    type Doxyfile
    echo GENERATE_HTML=NO
    echo GENERATE_XML=YES
    echo XML_OUTPUT=build\xml
    echo XML_PROGRAMLISTING=NO
) | doxygen -

mkdir build\html_extra\doxygen
(
    type Doxyfile
    echo HTML_OUTPUT=build\html_extra\doxygen
    echo INLINE_INHERITED_MEMB=YES
) | doxygen -

Jump over to a PowerShell terminal and run this to replace ndash with --.

cd /path/to/gdal/doc
Get-ChildItem "build\xml\*.xml" | ForEach-Object {
    (Get-Content $_.FullName) -replace '<ndash/>', '--' | Set-Content $_.FullName
}

Back in the miniforge terminal, run this command to actually build the docs. I did get quite a few warnings, but it did build for the most part, likely enough to feel comfortable with the tutorial additions. You can navigate to the build\html\index.html and open it in a browser to preview the work.

sphinx-build -M html source build --keep-going -j auto -W