doc: use describe instead of option for old Sphinx

Older versions of Sphinx will generate duplicate IDs when you have
options like:

.. option:: some-option

.. option:: some-other-option

The version of Sphinx provided on CentOS 7 has this issue, newer
versions of Sphinx do not.  As CentOS 7 is still a popular
distribution, change ".. option" to ".. describe" which has the
same visual output, but does not generate links.

diff --git a/doc/userguide/partials/commands-pcap-sc.rst b/doc/userguide/partials/commands-pcap-sc.rst
index fa7a3716d925bae24571e8ff9b90c83f5cd0985d..4e5e496613952a3ffc127f3f5984f2e09caeb897 100644 (file)
--- a/doc/userguide/partials/commands-pcap-sc.rst
+++ b/doc/userguide/partials/commands-pcap-sc.rst
@@ -1,32 +1,38 @@
-.. option:: pcap-file <file> <dir> [tenant] [continuous] [delete-when-done]
+.. Consider converting `.. description` to `.. option` when the
+   minimum version of Sphinx on the primary distributions are all
+   updated to generate duplicate reference links. For example, we
+   can't use `.. option` on CentOS 7 which has Sphinx 1.1.3, but
+   Fedora 30 with Sphinx 1.8.4 is fine.
+
+.. describe:: pcap-file <file> <dir> [tenant] [continuous] [delete-when-done]
 
    Add pcap files to Suricata for sequential processing. The generated
    log/alert files will be put into the directory specified as second argument.
    Make sure to provide absolute path to the files and directory. It is
    acceptable to add multiple files without waiting the result.
 
-.. option:: pcap-file-continuous <file> <dir> [tenant] [delete-when-done]
+.. describe:: pcap-file-continuous <file> <dir> [tenant] [delete-when-done]
 
    Add pcap files to Suricata for sequential processing. Directory will be
    monitored for new files being added until there is a use of
    **pcap-interrupt** or directory is moved or deleted.
 
-.. option:: pcap-file-number
+.. describe:: pcap-file-number
 
    Number of pcap files waiting to get processed.
 
-.. option:: pcap-file-list
+.. describe:: pcap-file-list
 
    List of queued pcap files.
 
-.. option:: pcap-last-processed
+.. describe:: pcap-last-processed
 
    Processed time of last file in milliseconds since epoch.
 
-.. option:: pcap-interrupt
+.. describe:: pcap-interrupt
 
    Terminate the current state by interrupting directory processing.
 
-.. option:: pcap-current
+.. describe:: pcap-current
 
    Currently processed file.

diff --git a/doc/userguide/partials/commands-sc.rst b/doc/userguide/partials/commands-sc.rst
index 30cbcd907a3127107d1d988df8713b7cbc1476f0..a21c2f20cad3fc69d971a21cbb0453f730a15d78 100644 (file)
--- a/doc/userguide/partials/commands-sc.rst
+++ b/doc/userguide/partials/commands-sc.rst
@@ -1,113 +1,119 @@
+.. Consider converting `.. description` to `.. option` when the
+   minimum version of Sphinx on the primary distributions are all
+   updated to generate duplicate reference links. For example, we
+   can't use `.. option` on CentOS 7 which has Sphinx 1.1.3, but
+   Fedora 30 with Sphinx 1.8.4 is fine.
+
 .. Start with the most common basic commands.
 
-.. option:: shutdown
+.. describe:: shutdown
 
    Shut Suricata instance down.
 
-.. option:: command-list
+.. describe:: command-list
 
    List available commands.
 
-.. option:: help
+.. describe:: help
 
    Get help about the available commands.
 
-.. option:: version
+.. describe:: version
 
    Print the version of Suricata instance.
 
-.. option:: uptime
+.. describe:: uptime
 
    Display the uptime of Suricata.
 
-.. option:: running-mode
+.. describe:: running-mode
 
    Display running mode. This can either be *workers*, *autofp* or *single*.
 
-.. option:: capture-mode
+.. describe:: capture-mode
 
    Display the capture mode. This can be either of *PCAP_DEV*,
    *PCAP_FILE*, *PFRING(DISABLED)*, *NFQ*, *NFLOG*, *IPFW*, *ERF_FILE*,
    *ERF_DAG*, *AF_PACKET_DEV*, *NETMAP(DISABLED)*, *UNIX_SOCKET* or
    *WINDIVERT(DISABLED)*.
 
-.. option:: conf-get <variable>
+.. describe:: conf-get <variable>
 
    Get configuration value for a given variable. Variable to be provided can be
    either of the configuration parameters that are written in suricata.yaml.
 
-.. option:: dump-counters
+.. describe:: dump-counters
 
    Dump Suricata's performance counters.
 
-.. option:: ruleset-reload-rules
+.. describe:: ruleset-reload-rules
 
    Reload the ruleset and wait for completion.
 
-.. option:: reload-rules
+.. describe:: reload-rules
 
-   Alias of option *ruleset-reload-rules*.
+   Alias .. describe *ruleset-reload-rules*.
 
-.. option:: ruleset-reload-nonblocking
+.. describe:: ruleset-reload-nonblocking
 
    Reload ruleset and proceed without waiting.
 
-.. option:: ruleset-reload-time
+.. describe:: ruleset-reload-time
 
    Return time of last reload.
 
-.. option:: ruleset-stats
+.. describe:: ruleset-stats
 
    Display the number of rules loaded and failed.
 
-.. option:: ruleset-failed-rules
+.. describe:: ruleset-failed-rules
 
    Display the list of failed rules.
 
-.. option:: register-tenant-handler <id> <htype> [hargs]
+.. describe:: register-tenant-handler <id> <htype> [hargs]
 
    Register a tenant handler with the specified mapping.
 
-.. option:: unregister-tenant-handler <id> <htype> [hargs]
+.. describe:: unregister-tenant-handler <id> <htype> [hargs]
 
    Unregister a tenant handler with the specified mapping.
 
-.. option:: register-tenant <id> <filename>
+.. describe:: register-tenant <id> <filename>
 
    Register tenant with a particular ID and filename.
 
-.. option:: reload-tenant <id> <filename>
+.. describe:: reload-tenant <id> <filename>
 
    Reload a tenant with specified ID and filename.
 
-.. option:: unregister-tenant <id>
+.. describe:: unregister-tenant <id>
 
    Unregister tenant with a particular ID.
 
-.. option:: add-hostbit <ipaddress> <hostbit> <expire>
+.. describe:: add-hostbit <ipaddress> <hostbit> <expire>
 
    Add hostbit on a host IP with a particular bit name and time of expiry.
 
-.. option:: remove-hostbit <ipaddress> <hostbit>
+.. describe:: remove-hostbit <ipaddress> <hostbit>
 
    Remove hostbit on a host IP with specified IP address and bit name.
 
-.. option:: list-hostbit <ipaddress>
+.. describe:: list-hostbit <ipaddress>
 
    List hostbit for a particular host IP.
 
-.. option:: reopen-log-files
+.. describe:: reopen-log-files
 
    Reopen log files to be run after external log rotation.
 
-.. option:: memcap-set <config> <memcap>
+.. describe:: memcap-set <config> <memcap>
 
    Update memcap value of a specified item.
 
-.. option:: memcap-show <config>
+.. describe:: memcap-show <config>
 
    Show memcap value of a specified item.
 
-.. option:: memcap-list
+.. describe:: memcap-list
 
    List all memcap values available.