IQSS / IQSS/dataverse

Idea: refactor config docs with custom sphinx role

Open
#7,694 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Feature: Admin Guide Feature: Developer Guide Feature: Installation Guide Type: Suggestion User Role: Sysadmin
Dominant language
Java
Stars
1.1k
Forks
564
Avg merge
2d 2h
Merged PRs (30d)
29

Description

Currently, the config docs are a bit scattered as mentioned in https://youtu.be/SevMNjTDTzs.
The list of config options is quite useful to gather an overview. Yet, the list might be incomplete and when we would split up the stuffed "Install Guide/Configuration" page into more pages on topics, it still would be a good thing to have a complete list of linkable and referencable options.

While hacking on a smallish PR for #6953, I had an idea for this. There are multiple extensions that provide custom roles, including rendering, linking, referencing and generating an index list.

Adding such a small extension to our Sphinx based guide (or develop as a separate extension) would make this possible. There is no maintained generic extension or builtin support to create these. (So we have to create an extension ourselfs...)

To provide an example: in a section about some configuration, one might add the following documentation about a setting:

.. dvoption::
   :key: <key string>
   :default: <default value>
   :allowedValues: ...
   :alias: <add old names here>
   :type: <mpconfig|db|...>
   :summary: <a short description>
   (...)
   This config option allows you to ... (long description here)

This would be rendered in place plus added to an index, that might be printed in a dedicated place by using .. dvoptionslist::.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the Sphinx-based guide and the existing Install Guide/Configuration page to map how configuration options are currently documented. Compare the proposed dvoption and dvoptionslist roles with available Sphinx extensions, then define the extension scope and a complete, linkable configuration index before implementation.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.