This is an example of a Sphinx plugin that can be used to pull in files outside the main docs directory. It does this by creating symlinks from those files into the main docs directory, where they are discoverable by Sphinx. It does mean the paths in index.rst look a little funny because they all point to long paths inside a symlinks folder, but it eliminates the need to make a bunch of files that are just includes of other files. Right now it works by making links to all .rst files in a repo. In theory, in the future it could be configurable to only copy docs the user cares about, and include other file extensions like .md.
If we decide to move forward with this we should make it a proper PyPI package so we can version it.
Description:
This is an example of a Sphinx plugin that can be used to pull in files outside the main docs directory. It does this by creating symlinks from those files into the main docs directory, where they are discoverable by Sphinx. It does mean the paths in index.rst look a little funny because they all point to long paths inside a
symlinks
folder, but it eliminates the need to make a bunch of files that are just includes of other files. Right now it works by making links to all .rst files in a repo. In theory, in the future it could be configurable to only copy docs the user cares about, and include other file extensions like .md.If we decide to move forward with this we should make it a proper PyPI package so we can version it.