[#442] Use a single unified sphinx project

Jynn Nelsonrequested to merge
jyn514/YDBDoc:442-unified-sphinx into master
  • Use a single shared LICENSE instead of rsync-ing to each directory
  • Remove duplicate files from .gitignore
  • After unifying, sphinx gave a warning:
/home/jyn/work/YDBDoc/AdminOpsGuide/dbrepl.rst:279: WARNING: duplicate citation a, other instance in /home/jyn/work/YDBDoc/ProgGuide/ioproc.rst
/home/jyn/work/YDBDoc/AdminOpsGuide/dbrepl.rst:281: WARNING: duplicate citation b, other instance in /home/jyn/work/YDBDoc/ProgGuide/ioproc.rst

It turns out that [a] is a "citation", not a "footnote", and hence can be referred to across documents, and so must be globally unique. Switch to [#a], which only needs to be unique per-page.

This changes the rendered note from a b superscript to a 2 superscript; hopefully that's ok.

  • Fix a broken link in isv.rst
  • Disambiguate duplicate links
  • Add a chapter heading to each subproject

This shows a more useful title in the sidebar on the left, and also prevents "Indices and tables" from being shown.

  • Fix sphinx caching and octo hyperlinks; see inline comments for more detail
  • Switch from hand-coded index.html to index.rst

This matches the style of the rest of the docs and is nicer to maintain. we need something like it anyway; sphinx would allow a separate toctree but that seems like extra work.

  • Rename ProgGuide to ProgrammersGuide

Sphinx generates hyperlinks to this and assumes it has the same name in the build and source directories. Rename the source directory so it's right.

This is necessary for unifying the subprojects, but it also seems like a good change in its own right.

Here are some screenshots showing the new rendered docs:

image image image image

Note that the sections now link to each other; we don't need a "Main YottaDB Documentation" section in the root of each subproject anymore. If you like, I am happy to remove them.

Note that Octo still does not link to the other projects; I would like to fix that but I was not able to. See the new comments in buildall.csh for more information.

For your reviewing convenience, the rename from ProgGuide to ProgrammersGuide is separated into its own commit.

Closes #442 (closed)

Merge request reports