Description
For some reason, the doc directory for our sources is set to ./static_root/doc
but Sphinx expects it to be at ./doc
and this has yet to be addressed. The effect of this discontinuity is that when Sphinx is running, it looks in the incorrect location with relative paths for static files we are serving up. This ultimately is not an issue for the functionality of the website as the links are indeed consistent in the static files generated, but it causes tests such as linkcheck
to fail. For this reason, this make command has been modified to accoun for this discontinuity to preserve the validity of the test, but this change may have impact on future modifications to the website's internal structure and/or a fix for this issue, hence the in-line documentation of the problem (which gets printed to the console upon linkcheck
's failure).
Here's what the make command was prior to this modification (and likely should be converted back to after addressing the issue):
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
Here's an overview of the logic for circumventing the issue:
- Attempt to create the symlink to the actual doc directory in the location that Sphinx expects it to be.
- Success
- Run
linkcheck
as we've properly configured our local structure to be what Sphinx expects. - Delete the symlink hack/patch, regardless of
linkcheck
's success as we know we create./doc
as a symlink in (1) (as opposed to it being a directory containing its own data possibly created at a later time without knowledge of this fix).
- Run
- Failure
- Do no proceed and let this message be printed for future debugging/maintainance effors.
- Success