docs: dash-dash-opt into literal or link

docs/gunicorn_ext.py

@@ -32,14 +32,17 @@
 ISSUE_URI = 'https://github.com/benoitc/gunicorn/issues/%s'
 PULL_REQUEST_URI = 'https://github.com/benoitc/gunicorn/pull/%s'
 
+def ref_section_header(title):
+    ref = title.lower().replace("_", "-").replace(" ", "-")
+    return ".. _%s:\n\n%s\n%s\n\n" % (ref, title, "-" * len(title))
 
 def format_settings(app):
     settings_file = os.path.join(app.srcdir, "settings.rst")
     ret = []
     known_settings = sorted(guncfg.KNOWN_SETTINGS, key=lambda s: s.section)
     for i, s in enumerate(known_settings):
         if i == 0 or s.section != known_settings[i - 1].section:
-            ret.append("%s\n%s\n\n" % (s.section, "-" * len(s.section)))
+            ret.append(ref_section_header(s.section))
         ret.append(fmt_setting(s))
 
     with open(settings_file, 'w') as settings:

docs/source/2010-news.rst

@@ -122,7 +122,7 @@ Changelog - 2010
 0.7.2 / 2010-04-15
 ------------------
 
-* Added --spew option to help debugging (installs a system trace hook)
+* Added :ref:`spew` option to help debugging (installs a system trace hook)
 * Some fixes in async arbiters
 * Fix a bug in start_response on error
 
@@ -172,7 +172,7 @@ Changelog - 2010
 ------------------
 
 * Added gunicorn config file support for Django admin command
-* Fix gunicorn config file. -c was broken.
+* Fix gunicorn config file. ``-c`` was broken.
 * Removed TTIN/TTOU from workers which blocked other signals.
 
 0.6.0 / 2010-02-22

docs/source/2012-news.rst

@@ -22,7 +22,7 @@ Changelog - 2012
 -------------------
 
 - **Added support for Python 3.2 & 3.3**
-- Expose --pythonpath command to all gunicorn commands
+- Expose :ref:`pythonpath` command to all gunicorn commands
 - Honor $PORT environment variable, useful for deployment on heroku
 - Removed support for Python 2.5
 - Make sure we reopen the logs on the console
@@ -66,7 +66,7 @@ Changelog - 2012
 0.14.4 / 2012-06-24
 -------------------
 
-- new --graceful-timeout option
+- new :ref:`graceful-timeout` option
 - fix multiple issues with request limit
 - more fixes in django settings resolutions
 - fix gevent.core import
@@ -109,10 +109,10 @@ Changelog - 2012
 -------------------
 
 - check if Request line is too large: You can now pass the parameter
-  ``--limit-request-line`` or set the ``limit_request_line`` in your
+  ``--limit-request-line`` or set the :ref:`limit-request-line` in your
   configuration file to set the max size of the request line in bytes.
 - limit the number of headers fields and their size. Add
-  ``--limit-request-field`` and ``limit-request-field-size`` settings
+  ``--limit-request-field`` and :ref:`limit-request-field-size` settings
 - add ``p`` variable to the log access format to log pidfile
 - add ``{HeaderName}o`` variable to the logo access format to log the
   response header HeaderName

docs/source/2013-news.rst

@@ -33,7 +33,7 @@ Changelog - 2013
   config file.
 - fix graceful timeout with the Eventlet worker
 - fix: don't raise an error when closing the socket if already closed
-- fix: fix --settings parameter for django application and try to find
+- fix: fix ``--settings`` parameter for django application and try to find
   the django settings when using the ``gunicorn`` command.
 - fix: give the initial global_conf to paster application
 - fix: fix 'Expect: 100-continue' support on Python 3

docs/source/2014-news.rst

@@ -95,17 +95,17 @@ Extra
 Documentation
 +++++++++++++
 
-- update faq: put a note on how `watch logs in the console
-  <http://docs.gunicorn.org/en/latest/faq.html#why-i-don-t-see-any-logs-in-the-console>`_
+- update faq: put a note on how :ref:`watch logs in the console
+  <why-i-don-t-see-any-logs-in-the-console>`
   since many people asked for it.
 
 
 19.0 / 2014-06-12
 =================
 
 Gunicorn 19.0 is a major release with new features and fixes. This
-version improve a lot the usage of Gunicorn with python 3 by adding `two
-new workers <http://docs.gunicorn.org/en/latest/design.html#asyncio-workers>`_
+version improve a lot the usage of Gunicorn with python 3 by adding
+:ref:`two new workers <async-workers>`
 to it: `gthread` a fully threaded async worker using futures and `gaiohttp` a
 worker using asyncio.
 
@@ -153,14 +153,14 @@ core
 - add support for python 3.4
 - fix: do not swallow unexpected errors when reaping
 - fix: remove incompatible SSL option with python 2.6
-- add new async gthread worker and `--threads` options allows to set multiple
+- add new async gthread worker and :ref:`threads` options allows to set multiple
   threads to listen on connection
 - deprecate `gunicorn_django` and `gunicorn_paster`
 - switch QUIT and TERM signal
 - reap workers in SIGCHLD handler
 - add universal wheel support
 - use `email.utils.formatdate` in gunicorn.util.http_date
-- deprecate the `--debug` option
+- deprecate the ``--debug`` option
 - fix: log exceptions that occur after response start …
 - allows loading of applications from `.pyc` files (#693)
 - fix: issue #691, raw_env config file parsing
@@ -171,7 +171,7 @@ core
   setups.
 - add: include tz offset in access log
 - add: include access logs in the syslog handler.
-- add --reload option for code reloading
+- add :ref:`reload` option for code reloading
 - add the capability to load `gunicorn.base.Application` without the loading of
   the arguments of the command line. It allows you to :ref:`embed gunicorn in
   your own application <custom>`.
@@ -181,7 +181,7 @@ core
 - fix logging: don't try to redirect stdout/stderr to the logfile.
 - fix logging: don't propagate log
 - improve logging: file option can be overridden by the gunicorn options
-  `--error-logfile` and `--access-logfile` if they are given.
+  :ref:`errorlog` and :ref:`accesslog` if they are given.
 - fix: don't override SERVER_* by the Host header
 - fix: handle_error
 - add more option to configure SSL

docs/source/2015-news.rst

@@ -19,7 +19,7 @@ Core
 
 - improvement: handle HaltServer in manage_workers (:issue:`1095`)
 - fix: Do not rely on sendfile sending requested count (:issue:`1155`)
-- fix: claridy --no-sendfile default (:issue:`1156`)
+- fix: clarify :ref:`sendfile` default (:issue:`1156`)
 - fix: LoggingCatch sendfile failure from no file descriptor (:issue:`1160`)
 
 Logging
@@ -122,9 +122,9 @@ Documentation
 - don't duplicate NGINX config files examples (:issue:`1050`, :issue:`1048`)
 - add `web.py` framework example (:issue:`1117`)
 - update Debian/Ubuntu installations instructions (:issue:`1112`)
-- clarify `pythonpath` setting description (:issue:`1080`)
+- clarify ref:`pythonpath` setting description (:issue:`1080`)
 - tweak some example for python3
-- clarify `sendfile` documentation
+- clarify ref:`sendfile` documentation
 - miscellaneous typos in source code comments (thanks!)
 - clarify why REMOTE_ADD may not be the user's IP address (:issue:`1037`)
 
@@ -186,9 +186,9 @@ Core
 ++++
 
 - optimize the sync workers when listening on a single interface
-- add `--sendfile` settings to enable/disable sendfile. fix :issue:`856` .
+- add :ref:`sendfile` settings to enable/disable sendfile. fix :issue:`856` .
 - add the selectors module to the code base. :issue:`886`
-- add `--max-requests-jitter` setting to set the maximum jitter to add to the
+- add :ref:`max-requests-jitter` setting to set the maximum jitter to add to the
   max-requests setting.
 - fix :issue:`899` propagate proxy_protocol_info to keep-alive requests
 - fix :issue:`863` worker timeout: dynamic timeout has been removed

docs/source/2017-news.rst

@@ -23,13 +23,13 @@ Changelog - 2017
   ``ssl.PROTOCOL_TLSv1`` to ``ssl.PROTOCOL_SSLv23``.
 - fix: initialize the group access list when initgroups is set (:issue:`1297`)
 - add environment variables to gunicorn access log format (:issue:`1291`)
-- add --paste-global-conf option (:issue:`1304`)
+- add :ref:`raw-paste-global-conf` option (:issue:`1304`)
 - fix: print access logs to STDOUT (:issue:`1184`)
 - remove upper limit on max header size config (:issue:`1313`)
 - fix: print original exception on AppImportError (:issue:`1334`)
 - use SO_REUSEPORT if available (:issue:`1344`)
 - `fix leak <https://github.com/benoitc/gunicorn/commit/b4c41481e2d5ef127199a4601417a6819053c3fd>`_ of duplicate file descriptor for bound sockets.
-- add --reload-engine option, support inotify and other backends (:issue:`1368`, :issue:`1459`)
+- add :ref:`reload-engine` option, support inotify and other backends (:issue:`1368`, :issue:`1459`)
 - fix: reject request with invalid HTTP versions
 - add ``child_exit`` callback (:issue:`1394`)
 - add support for eventlets _AlreadyHandled object (:issue:`1406`)

docs/source/2019-news.rst

@@ -95,10 +95,10 @@ Changelog - 2019
 - Fixed typo in gthread.py
 - Added `tornado <https://www.tornadoweb.org/>`_ 5 and  6 support
 - Declare our setuptools dependency
-- Added support to `--bind` to open file descriptors
+- Added support to :ref:`bind` to open file descriptors
 - Document how to serve WSGI app modules from Gunicorn
 - Provide guidance on X-Forwarded-For access log in documentation
-- Add support for named constants in the `--ssl-version` flag
+- Add support for named constants in the :ref:`ssl-version` flag
 - Clarify log format usage of header & environment in documentation
 - Fixed systemd documentation to properly setup gunicorn unix socket
 - Prevent removal unix socket for reuse_port
@@ -108,7 +108,7 @@ Changelog - 2019
 - fixed `InotifyReloadeder`:  handle `module.__file__` is None
 - `/dev/shm` as a convenient alternative to making your own tmpfs mount in fchmod FAQ
 - fix examples to work on python3
-- Fix typo in `--max-requests` documentation
+- Fix typo in :ref:`max-requests` documentation
 - Clear tornado ioloop before os.fork
 - Miscellaneous fixes and improvement for linting using Pylint
 

docs/source/2021-news.rst

@@ -17,7 +17,7 @@ Changelog - 2021
 - add support for python -m gunicorn
 - fix systemd socket activation example
 - allows to set wsgi application in config file using `wsgi_app`
-- document `--timeout = 0`
+- document ``--``:ref:`timeout=0<timeout>`
 - always close a connection when the number of requests exceeds the max requests
 - Disable keepalive during graceful shutdown
 - kill tasks in the gthread workers during upgrade
@@ -30,11 +30,11 @@ Changelog - 2021
 - added PIP requirements to be used for example
 - remove version from the Server header
 - fix sendfile: use `socket.sendfile` instead of `os.sendfile`
-- reloader: use  absolute path to prevent empty to prevent0 `InotifyError` when a file 
+- reloader: use  absolute path to prevent `InotifyError` when a file
   is added to the working directory
-- Add --print-config option to print the resolved settings at startup.
-- remove the `--log-dict-config` CLI flag because it never had a working format
-  (the `logconfig_dict` setting in configuration files continues to work)
+- Add :ref:`print-config` option to print the resolved settings at startup.
+- remove the ``--log-dict-config`` CLI flag because it never had a working format
+  (the :ref:`logconfig-dict` setting in configuration files continues to work)
 
 
 ** Breaking changes **

docs/source/deploy.rst

@@ -350,7 +350,7 @@ Logging
 =======
 
 Logging can be configured by using various flags detailed in the
-`configuration documentation`_ or by creating a `logging configuration file`_.
+:ref:`configuration documentation<logging>` or by creating a `logging configuration file`_.
 Send the ``USR1`` signal to rotate logs if you are using the logrotate
 utility::
 
@@ -372,7 +372,6 @@ utility::
 .. _`example service`: https://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc
 .. _Supervisor: http://supervisord.org/
 .. _`simple configuration`: https://github.com/benoitc/gunicorn/blob/master/examples/supervisor.conf
-.. _`configuration documentation`: http://docs.gunicorn.org/en/latest/settings.html#logging
 .. _`logging configuration file`: https://github.com/benoitc/gunicorn/blob/master/examples/logging.conf
 .. _Virtualenv: https://pypi.python.org/pypi/virtualenv
 .. _Systemd: https://www.freedesktop.org/wiki/Software/systemd/

docs/source/design.rst

@@ -38,6 +38,8 @@ applications are programmed.
 closed after response has been sent (even if you manually add ``Keep-Alive``
 or ``Connection: keep-alive`` header in your application).
 
+.. _async-workers:
+
 Async Workers
 -------------
 

docs/source/faq.rst

@@ -109,6 +109,8 @@ threads. However `a work has been started
 .. _worker_class: settings.html#worker-class
 .. _`number of workers`: design.html#how-many-workers
 
+.. _why-i-don-t-see-any-logs-in-the-console:
+
 Why I don't see any logs in the console?
 ----------------------------------------
 

docs/source/run.rst

@@ -121,11 +121,10 @@ So for a typical Django project, invoking Gunicorn would look like::
    ``manage.py`` file.
 
 You can use the
-`--env <http://docs.gunicorn.org/en/latest/settings.html#raw-env>`_ option
+:ref:`raw-env` option
 to set the path to load the settings. In case you need it you can also
 add your application path to ``PYTHONPATH`` using the
-`--pythonpath <http://docs.gunicorn.org/en/latest/settings.html#pythonpath>`_
-option::
+:ref:`pythonpath` option::
 
     $ gunicorn --env DJANGO_SETTINGS_MODULE=myproject.settings myproject.wsgi
 
@@ -150,19 +149,19 @@ commands, specify it as a server in your configuration file:
 
 This approach is the quickest way to get started with Gunicorn, but there are
 some limitations. Gunicorn will have no control over how the application is
-loaded, so settings such as reload_ will have no effect and Gunicorn will be
-unable to hot upgrade a running application. Using the daemon_ option may
+loaded, so settings such as :ref:`reload` will have no effect and Gunicorn will be
+unable to hot upgrade a running application. Using the :ref:`daemon` option may
 confuse your command line tool. Instead, use the built-in support for these
 features provided by that tool. For example, run ``pserve --reload`` instead of
 specifying ``reload = True`` in the server configuration block. For advanced
-configuration of Gunicorn, such as `Server Hooks`_ specifying a Gunicorn
+configuration of Gunicorn, such as :ref:`server-hooks` specifying a Gunicorn
 configuration file using the ``config`` key is supported.
 
 To use the full power of Gunicorn's reloading and hot code upgrades, use the
-`paste option`_ to run your application instead. When used this way, Gunicorn
+:ref:`paste` to run your application instead. When used this way, Gunicorn
 will use the application defined by the PasteDeploy configuration file, but
 Gunicorn will not use any server configuration defined in the file. Instead,
-`configure gunicorn`_.
+:ref:`configure gunicorn<settings>`.
 
 For example::
 
@@ -174,11 +173,4 @@ Or use a different application::
 
 With both approaches, Gunicorn will use any loggers section found in Paste
 Deployment configuration file, unless instructed otherwise by specifying
-additional `logging settings`_.
-
-.. _reload: http://docs.gunicorn.org/en/latest/settings.html#reload
-.. _daemon: http://docs.gunicorn.org/en/latest/settings.html#daemon
-.. _Server Hooks: http://docs.gunicorn.org/en/latest/settings.html#server-hooks
-.. _paste option: http://docs.gunicorn.org/en/latest/settings.html#paste
-.. _configure gunicorn: http://docs.gunicorn.org/en/latest/configure.html
-.. _logging settings: http://docs.gunicorn.org/en/latest/settings.html#logging
+additional :ref:`logging settings<logging>`.