Create AWX docsite with RST content

.gitignore

@@ -165,3 +165,6 @@ use_dev_supervisor.txt
 
 awx/ui_next/src
 awx/ui_next/build
+
+# Docs build
+docs/docsite/build/

docs/docsite/conf.py

@@ -0,0 +1,90 @@
+import sys
+import os
+import shlex
+
+from datetime import datetime
+from importlib import import_module
+
+#sys.path.insert(0, os.path.abspath('./rst/rest_api/_swagger'))
+
+project = u'Ansible AWX'
+copyright = u'2023, Red Hat'
+author = u'Red Hat'
+
+pubdateshort = '2023-08-04'
+pubdate = datetime.strptime(pubdateshort, '%Y-%m-%d').strftime('%B %d, %Y')
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+html_title = 'Ansible AWX community documentation'
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+html_short_title = 'AWX community documentation'
+
+htmlhelp_basename = 'AWX_docs'
+
+# include the swagger extension to build rest api reference
+#'swagger',
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.ifconfig',
+    'sphinx_ansible_theme',
+]
+
+html_theme = 'sphinx_ansible_theme'
+html_theme_path = ["_static"]
+
+pygments_style = "ansible"
+highlight_language = "YAML+Jinja"
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+version = 'latest'
+shortversion = 'latest'
+# The full version, including alpha/beta/rc tags.
+release = 'AWX latest'
+
+language = 'en'
+
+locale_dirs = ['locale/']   # path is example but recommended.
+gettext_compact = False     # optional.
+
+rst_epilog = """
+.. |atqi| replace:: *AWX Quick Installation Guide*
+.. |atqs| replace:: *AWX Quick Setup Guide*
+.. |atir| replace:: *AWX Installation and Reference Guide*
+.. |ata| replace:: *AWX Administration Guide*
+.. |atu| replace:: *AWX User Guide*
+.. |atumg| replace:: *AWX Upgrade and Migration Guide*
+.. |atapi| replace:: *AWX API Guide*
+.. |atrn| replace:: *AWX Release Notes*
+.. |aa| replace:: Ansible Automation
+.. |AA| replace:: Automation Analytics
+.. |aap| replace:: Ansible Automation Platform
+.. |ab| replace:: ansible-builder
+.. |ap| replace:: Automation Platform
+.. |at| replace:: automation controller
+.. |At| replace:: Automation controller
+.. |ah| replace:: Automation Hub
+.. |EE| replace:: Execution Environment
+.. |EEs| replace:: Execution Environments
+.. |Ee| replace:: Execution environment
+.. |Ees| replace:: Execution environments
+.. |ee| replace:: execution environment
+.. |ees| replace:: execution environments
+.. |versionshortest| replace:: v%s
+.. |pubdateshort| replace:: %s
+.. |pubdate| replace:: %s
+.. |rhel| replace:: Red Hat Enterprise Linux
+.. |rhaa| replace:: Red Hat Ansible Automation
+.. |rhaap| replace:: Red Hat Ansible Automation Platform
+.. |RHAT| replace:: Red Hat Ansible Automation Platform controller
+
+""" % (version, pubdateshort, pubdate)

docs/docsite/requirements.txt

@@ -0,0 +1,5 @@
+sphinx==5.1.1
+sphinx-ansible-theme==0.9.1
+docutils==0.16
+Jinja2<3.1
+PyYaml

docs/docsite/rst/administration/authentication_timeout.rst

@@ -0,0 +1,31 @@
+Changing the Default Timeout for Authentication
+=================================================
+
+.. index::
+   pair: troubleshooting; authentication timeout
+   pair: authentication timeout; changing the default
+   single: authentication token
+   single: authentication expiring
+   single: log
+   single: login timeout
+   single: timeout login
+   pair: timeout; session
+
+
+The default length of time, in seconds, that your supplied token is valid can be changed in the System Settings screen of the AWX user interface:
+
+1. Click the **Settings** from the left navigation bar.  
+
+3. Click **Miscellaneous Authentication settings** under the System settings.
+
+3. Click **Edit**.
+
+4. Enter the timeout period in seconds in the **Idle Time Force Log Out** text field.
+
+.. image:: ../common/images/configure-awx-system-timeout.png
+
+4. Click **Save** to apply your changes.
+
+.. note::
+
+  If you are accessing AWX directly and are having trouble getting your authentication to stay, in that you have to keep logging in over and over, try clearing your web browser's cache. In situations like this, it is often found that the authentication token has been cached in the browser session and must be cleared.

docs/docsite/rst/administration/awx-manage.rst

@@ -0,0 +1,198 @@
+.. _ag_manage_utility:
+
+The *awx-manage* Utility
+-------------------------------
+
+.. index:: 
+   single: awx-manage
+
+The ``awx-manage`` utility is used to access detailed internal information of AWX. Commands for ``awx-manage`` should run as the ``awx`` or ``root`` user.
+
+.. warning:: 
+         Running awx-manage commands via playbook is not recommended or supported.
+
+Inventory Import
+~~~~~~~~~~~~~~~~
+
+.. index:: 
+   single: awx-manage; inventory import
+
+``awx-manage`` is a mechanism by which an AWX administrator can import inventory directly into AWX, for those who cannot use Custom Inventory Scripts.
+
+To use ``awx-manage`` properly, you must first create an inventory in AWX to use as the destination for the import.
+
+For help with ``awx-manage``, run the following command: ``awx-manage inventory_import [--help]``
+
+The ``inventory_import`` command synchronizes an AWX inventory object with a text-based inventory file, dynamic inventory script, or a directory of one or more of the above as supported by core Ansible.
+
+When running this command, specify either an ``--inventory-id`` or ``--inventory-name``, and the path to the Ansible inventory source (``--source``).
+
+::
+
+    awx-manage inventory_import --source=/ansible/inventory/ --inventory-id=1 
+
+By default, inventory data already stored in AWX blends with data from the external source. To use only the external data, specify ``--overwrite``. To specify that any existing hosts get variable data exclusively from the ``--source``, specify ``--overwrite_vars``. The default behavior adds any new variables from the external source, overwriting keys that already exist, but preserves any variables that were not sourced from the external data source.
+
+::
+
+    awx-manage inventory_import --source=/ansible/inventory/ --inventory-id=1 --overwrite
+
+
+.. include:: ../common/overwrite_var_note_2-4-0.rst
+
+
+Cleanup of old data
+~~~~~~~~~~~~~~~~~~~
+
+.. index:: 
+   single: awx-manage, data cleanup
+
+``awx-manage`` has a variety of commands used to clean old data from AWX. The AWX administrators can use the Management Jobs interface for access or use the command line. 
+
+-  ``awx-manage cleanup_jobs [--help]``
+
+This permanently deletes the job details and job output for jobs older than a specified number of days.
+
+-  ``awx-manage cleanup_activitystream [--help]``
+
+This permanently deletes any :ref:`ug_activitystreams` data older than a specific number of days.
+
+Cluster management
+~~~~~~~~~~~~~~~~~~~~
+
+.. index:: 
+   single: awx-manage; cluster management
+
+Refer to the :ref:`ag_clustering` section for details on the
+``awx-manage provision_instance`` and ``awx-manage deprovision_instance``
+commands.
+
+
+.. note::
+    Do not run other ``awx-manage`` commands unless instructed by Ansible Support.
+
+
+.. _ag_token_utility:
+
+Token and session management
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. index:: 
+   single: awx-manage; token management
+   single: awx-manage; session management
+
+AWX supports the following commands for OAuth2 token management:
+
+.. contents::
+    :local:
+
+
+``create_oauth2_token``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use this command to create OAuth2 tokens (specify actual username for ``example_user`` below):
+
+::
+
+	$ awx-manage create_oauth2_token --user example_user
+
+	New OAuth2 token for example_user: j89ia8OO79te6IAZ97L7E8bMgXCON2
+
+Make sure you provide a valid user when creating tokens. Otherwise, you will get an error message that you tried to issue the command without specifying a user, or supplying a username that does not exist.
+
+
+.. _ag_manage_utility_revoke_tokens:
+
+
+``revoke_oauth2_tokens``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use this command to revoke OAuth2 tokens (both application tokens and personal access tokens (PAT)). By default, it revokes all application tokens (but not their associated refresh tokens), and revokes all personal access tokens. However, you can also specify a user for whom to revoke all tokens.
+
+To revoke all existing OAuth2 tokens: 
+
+::
+
+	$ awx-manage revoke_oauth2_tokens
+
+To revoke all OAuth2 tokens & their refresh tokens: 
+
+::
+
+	$ awx-manage revoke_oauth2_tokens --revoke_refresh
+
+To revoke all OAuth2 tokens for the user with ``id=example_user`` (specify actual username for ``example_user`` below):
+
+::
+
+	$ awx-manage revoke_oauth2_tokens --user example_user
+
+To revoke all OAuth2 tokens and refresh token for the user with ``id=example_user``:
+
+::
+
+	$ awx-manage revoke_oauth2_tokens --user example_user --revoke_refresh
+
+
+
+``cleartokens``
+^^^^^^^^^^^^^^^^^^^
+
+Use this command to clear tokens which have already been revoked. Refer to `Django's Oauth Toolkit documentation on cleartokens`_ for more detail.
+
+	.. _`Django's Oauth Toolkit documentation on cleartokens`: https://django-oauth-toolkit.readthedocs.io/en/latest/management_commands.html
+
+
+``expire_sessions``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use this command to terminate all sessions or all sessions for a specific user. Consider using this command when a user changes role in an organization, is removed from assorted groups in LDAP/AD, or the administrator wants to ensure the user can no longer execute jobs due to membership in these groups.
+
+::
+
+	$ awx-manage expire_sessions
+
+
+This command terminates all sessions by default. The users associated with those sessions will be consequently logged out. To only expire the sessions of a specific user, you can pass their username using the ``--user`` flag (specify actual username for ``example_user`` below):
+
+::
+
+	$ awx-manage expire_sessions --user example_user
+
+
+
+``clearsessions``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use this command to delete all sessions that have expired. Refer to `Django's documentation on clearsessions`_ for more detail.
+
+	.. _`Django's documentation on clearsessions`: https://docs.djangoproject.com/en/2.1/topics/http/sessions/#clearing-the-session-store
+
+
+
+For more information on OAuth2 token management in the AWX user interface, see the :ref:`ug_applications_auth` section of the |atu|.
+
+
+Analytics gathering
+~~~~~~~~~~~~~~~~~~~~~
+
+.. index:: 
+   single: awx-manage; data collection
+   single: awx-manage; analytics gathering
+
+
+Use this command to gather analytics on-demand outside of the predefined window (default is 4 hours):
+
+::
+
+	$ awx-manage gather_analytics --ship
+
+
+For customers with disconnected environments who want to collect usage information about unique hosts automated across a time period, use this command: 
+
+::
+
+  awx-manage host_metric --since YYYY-MM-DD --until YYYY-MM-DD --json
+
+
+The parameters ``--since`` and ``--until`` specify date ranges and are optional, but one of them has to be present. The ``--json`` flag specifies the output format and is optional.