From 28f7c2a3c1fe117de91c185f7c48d5c8134f8c08 Mon Sep 17 00:00:00 2001 From: "Paul J. Dorn" Date: Sun, 24 Nov 2024 21:06:30 +0100 Subject: [PATCH] docs: dash-dash-opt into literal or link --- docs/gunicorn_ext.py | 5 +++- docs/source/2010-news.rst | 4 +-- docs/source/2012-news.rst | 8 ++--- docs/source/2013-news.rst | 2 +- docs/source/2014-news.rst | 16 +++++----- docs/source/2015-news.rst | 10 +++---- docs/source/2017-news.rst | 4 +-- docs/source/2019-news.rst | 6 ++-- docs/source/2021-news.rst | 10 +++---- docs/source/deploy.rst | 3 +- docs/source/design.rst | 2 ++ docs/source/faq.rst | 2 ++ docs/source/run.rst | 24 +++++---------- docs/source/settings.rst | 62 ++++++++++++++++++++++++++------------- gunicorn/config.py | 42 +++++++++++++------------- 15 files changed, 109 insertions(+), 91 deletions(-) diff --git a/docs/gunicorn_ext.py b/docs/gunicorn_ext.py index 4310162eb..907135c1f 100755 --- a/docs/gunicorn_ext.py +++ b/docs/gunicorn_ext.py @@ -32,6 +32,9 @@ 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") @@ -39,7 +42,7 @@ def format_settings(app): 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: diff --git a/docs/source/2010-news.rst b/docs/source/2010-news.rst index e58c48198..8229877b6 100644 --- a/docs/source/2010-news.rst +++ b/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 diff --git a/docs/source/2012-news.rst b/docs/source/2012-news.rst index ce4f7cc4d..387d1155f 100644 --- a/docs/source/2012-news.rst +++ b/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 diff --git a/docs/source/2013-news.rst b/docs/source/2013-news.rst index eb8cf556a..8baa1aa8e 100644 --- a/docs/source/2013-news.rst +++ b/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 diff --git a/docs/source/2014-news.rst b/docs/source/2014-news.rst index 3eec18fcd..ace5a81bc 100644 --- a/docs/source/2014-news.rst +++ b/docs/source/2014-news.rst @@ -95,8 +95,8 @@ Extra Documentation +++++++++++++ -- update faq: put a note on how `watch logs in the console - `_ +- update faq: put a note on how :ref:`watch logs in the console + ` since many people asked for it. @@ -104,8 +104,8 @@ Documentation ================= 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 `_ +version improve a lot the usage of Gunicorn with python 3 by adding +:ref:`two new 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 `. @@ -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 diff --git a/docs/source/2015-news.rst b/docs/source/2015-news.rst index 61ea225b4..29345dbea 100644 --- a/docs/source/2015-news.rst +++ b/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 diff --git a/docs/source/2017-news.rst b/docs/source/2017-news.rst index 0fb201e61..a5fd6d091 100644 --- a/docs/source/2017-news.rst +++ b/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 `_ 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`) diff --git a/docs/source/2019-news.rst b/docs/source/2019-news.rst index 28b69216b..8635fd33c 100644 --- a/docs/source/2019-news.rst +++ b/docs/source/2019-news.rst @@ -95,10 +95,10 @@ Changelog - 2019 - Fixed typo in gthread.py - Added `tornado `_ 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 diff --git a/docs/source/2021-news.rst b/docs/source/2021-news.rst index 3057600de..44148863d 100644 --- a/docs/source/2021-news.rst +++ b/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` - 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 ** diff --git a/docs/source/deploy.rst b/docs/source/deploy.rst index 5f8689793..de582cba5 100644 --- a/docs/source/deploy.rst +++ b/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` 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/ diff --git a/docs/source/design.rst b/docs/source/design.rst index b366fbabc..e975a4a5c 100644 --- a/docs/source/design.rst +++ b/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 ------------- diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 8c52a4865..d43a94b42 100644 --- a/docs/source/faq.rst +++ b/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? ---------------------------------------- diff --git a/docs/source/run.rst b/docs/source/run.rst index 108956b83..6330160c8 100644 --- a/docs/source/run.rst +++ b/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 `_ 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 `_ -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`. 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`. diff --git a/docs/source/settings.rst b/docs/source/settings.rst index e1e91fa76..385a0f6f6 100644 --- a/docs/source/settings.rst +++ b/docs/source/settings.rst @@ -20,6 +20,8 @@ for reference on setting at the command line. .. versionadded:: 19.7 +.. _config-file: + Config File ----------- @@ -57,6 +59,8 @@ A WSGI application path in pattern ``$(MODULE_NAME):$(VARIABLE_NAME)``. .. versionadded:: 20.1.0 +.. _debugging: + Debugging --------- @@ -155,6 +159,8 @@ configuration is correct, and 1 if the configuration is incorrect. Print the configuration settings as fully resolved. Implies :ref:`check-config`. +.. _logging: + Logging ------- @@ -461,6 +467,8 @@ if not provided). .. versionadded:: 19.2 +.. _process-naming: + Process Naming -------------- @@ -491,6 +499,8 @@ If not set, the *default_proc_name* setting will be used. Internal setting that is adjusted for each type of application. +.. _ssl: + SSL --- @@ -530,20 +540,20 @@ SSL version to use (see stdlib ssl module's). .. deprecated:: 21.0 The option is deprecated and it is currently ignored. Use :ref:`ssl-context` instead. -============= ============ ---ssl-version Description -============= ============ -SSLv3 SSLv3 is not-secure and is strongly discouraged. -SSLv23 Alias for TLS. Deprecated in Python 3.6, use TLS. -TLS Negotiate highest possible version between client/server. - Can yield SSL. (Python 3.6+) -TLSv1 TLS 1.0 -TLSv1_1 TLS 1.1 (Python 3.4+) -TLSv1_2 TLS 1.2 (Python 3.4+) -TLS_SERVER Auto-negotiate the highest protocol version like TLS, - but only support server-side SSLSocket connections. - (Python 3.6+) -============= ============ +================= ============ +``--ssl-version`` Description +================= ============ +`SSLv3`` SSLv3 is not-secure and is strongly discouraged. +`SSLv23`` Alias for TLS. Deprecated in Python 3.6, use TLS. +`TLS`` Negotiate highest possible version between client/server. + Can yield SSL. (Python 3.6+) +`TLSv1`` TLS 1.0 +`TLSv1_1`` TLS 1.1 (Python 3.4+) +`TLSv1_2`` TLS 1.2 (Python 3.4+) +`TLS_SERVER`` Auto-negotiate the highest protocol version like TLS, + but only support server-side SSLSocket connections. + (Python 3.6+) +================= ============ .. versionchanged:: 19.7 The default value has been changed from ``ssl.PROTOCOL_TLSv1`` to @@ -566,13 +576,13 @@ TLS_SERVER Auto-negotiate the highest protocol version like TLS, Whether client certificate is required (see stdlib ssl module's) -=========== =========================== ---cert-reqs Description -=========== =========================== -`0` no client verification -`1` ssl.CERT_OPTIONAL -`2` ssl.CERT_REQUIRED -=========== =========================== +=============== =========================== +``--cert-reqs`` Description +=============== =========================== +`0` no client verification +`1` ssl.CERT_OPTIONAL +`2` ssl.CERT_REQUIRED +=============== =========================== .. _ca-certs: @@ -631,6 +641,8 @@ See the `OpenSSL Cipher List Format Documentation `_ for details on the format of an OpenSSL cipher list. +.. _security: + Security -------- @@ -690,6 +702,8 @@ header field sizes. Setting this parameter to a very high or unlimited value can open up for DDOS attacks. +.. _server-hooks: + Server Hooks ------------ @@ -984,6 +998,8 @@ Following example shows a configuration file that sets the minimum TLS version t .. versionadded:: 21.0 +.. _server-mechanics: + Server Mechanics ---------------- @@ -1560,6 +1576,8 @@ on a proxy in front of Gunicorn. .. versionadded:: 22.0.0 +.. _server-socket: + Server Socket ------------- @@ -1609,6 +1627,8 @@ load. Must be a positive integer. Generally set in the 64-2048 range. +.. _worker-processes: + Worker Processes ---------------- diff --git a/gunicorn/config.py b/gunicorn/config.py index 402a26b68..ffb811ffe 100644 --- a/gunicorn/config.py +++ b/gunicorn/config.py @@ -2138,20 +2138,20 @@ class SSLVersion(Setting): .. deprecated:: 21.0 The option is deprecated and it is currently ignored. Use :ref:`ssl-context` instead. - ============= ============ - --ssl-version Description - ============= ============ - SSLv3 SSLv3 is not-secure and is strongly discouraged. - SSLv23 Alias for TLS. Deprecated in Python 3.6, use TLS. - TLS Negotiate highest possible version between client/server. - Can yield SSL. (Python 3.6+) - TLSv1 TLS 1.0 - TLSv1_1 TLS 1.1 (Python 3.4+) - TLSv1_2 TLS 1.2 (Python 3.4+) - TLS_SERVER Auto-negotiate the highest protocol version like TLS, - but only support server-side SSLSocket connections. - (Python 3.6+) - ============= ============ + ================= ============ + ``--ssl-version`` Description + ================= ============ + `SSLv3`` SSLv3 is not-secure and is strongly discouraged. + `SSLv23`` Alias for TLS. Deprecated in Python 3.6, use TLS. + `TLS`` Negotiate highest possible version between client/server. + Can yield SSL. (Python 3.6+) + `TLSv1`` TLS 1.0 + `TLSv1_1`` TLS 1.1 (Python 3.4+) + `TLSv1_2`` TLS 1.2 (Python 3.4+) + `TLS_SERVER`` Auto-negotiate the highest protocol version like TLS, + but only support server-side SSLSocket connections. + (Python 3.6+) + ================= ============ .. versionchanged:: 19.7 The default value has been changed from ``ssl.PROTOCOL_TLSv1`` to @@ -2174,13 +2174,13 @@ class CertReqs(Setting): desc = """\ Whether client certificate is required (see stdlib ssl module's) - =========== =========================== - --cert-reqs Description - =========== =========================== - `0` no client verification - `1` ssl.CERT_OPTIONAL - `2` ssl.CERT_REQUIRED - =========== =========================== + =============== =========================== + ``--cert-reqs`` Description + =============== =========================== + `0` no client verification + `1` ssl.CERT_OPTIONAL + `2` ssl.CERT_REQUIRED + =============== =========================== """