diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index 32d0d3165..69265abb8 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -1,5 +1,9 @@ # Unreleased +## 📚 Documentation + +* Added new entries to the frequently asked questions regarding `multiversion documentation` + ## 🐞 Fixed * Added multi-version extension to Sphinx configuration of the project template diff --git a/doc/faq.rst b/doc/faq.rst index 2363a80ce..77c4c3782 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -23,3 +23,43 @@ Duplicated label error when building documentation -------------------------------------------------- Similar error to :code:`Warning, treated as error: integration-test-docker-environment/doc/changes/changes_0.10.0.md:5:duplicate label summary, other instance in integration-test-docker-environment/doc/changes/changes_0.1.0.md'`, might be caused by sphinx extension `sphinx.ext.autosectionlabel`. Try to remove this extension in `doc/conf.py`. + + +.. _faq_multiversion_build_warnings: + +Warning while building multiversion documentation +-------------------------------------------------- +When running ``nox -s docs:multiversion``, I receive the following warnings during the build: + +.. code-block:: + + WARNING: unknown config value 'smv_metadata_path' in override, ignoring + WARNING: unknown config value 'smv_current_version' in override, ignoring + +If you receive the warnings above, it is very likely that the multiversion extension is not configured in your Sphinx configuration (``conf.py``). Try adding it to your configuration and rerun the build. + +.. code-block:: python + + extensions = [ + ..., + ..., + "exasol.toolbox.sphinx.multiversion", + ] + + +.. _faq_multiversion_selection_missing: + +Missing Version Selection Box in Multiversion Documentation +------------------------------------------------------------ + +I have run ``nox -s docs:multiversion``, but I still do not see any version selection box in the upper right corner before the GitHub symbol. + +This is likely due to :ref:`faq_multiversion_build_warnings` + + +.. _faq_multiversion_limited_versions: + +Limited Previous Versions in Multiversion Documentation +------------------------------------------------------- + +If not all previous versions of the project are available via the version selection box of the multiversion documentation, it is likely due to the fact that the unavailable documentation for those versions was not in a compatible format (there hasn't been a compatible setup of a Sphinx-based documentation).