X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=blobdiff_plain;f=docs%2Fjjb%2Flf-python-jobs.rst;h=117ab3875191f9ca2aa28f7e929318f245008d7b;hb=fa47f310c90d788d8970651b255aa789fc4c8278;hp=3b142647047aeaf2b981e3cd09879669bcb162ca;hpb=30a6dacd8befef0dc78942a53068fa52a101cc9f;p=releng%2Fglobal-jjb.git

diff --git a/docs/jjb/lf-python-jobs.rst b/docs/jjb/lf-python-jobs.rst
index 3b142647..117ab387 100644
--- a/docs/jjb/lf-python-jobs.rst
+++ b/docs/jjb/lf-python-jobs.rst
@@ -361,20 +361,25 @@ pyenv variables before running.
    export PYENV_ROOT="/opt/pyenv"
    export PATH="$PYENV_ROOT/bin:$PATH"
 
-Installable package projects should consider using a directory layout
-like the one shown below. All Python files are below a directory, and
-the package source files are nested in a subdirectory. This layout
-allows straightforward build-job triggers using the directory paths so
-Jenkins jobs are triggered appropriately. For example, a PyPI merge
-job should not be triggered by a non-Python change, because the job
-cannot upload the same package twice.
+Installable package projects should use the directory layout shown
+below. All Python files are in a repo subdirectory separate from
+non-Python files like documentation. This layout allows highly
+specific build-job triggers in Jenkins using the subdirectory
+paths. For example, a PyPI merge job should not run on a non-Python
+file change such as documentation, because the job cannot upload the
+same package twice.
+
+To make the document files available for building a Python package
+long description in setup.py, add a symbolic link "docs" in the
+package subdirectory pointing to the top-level docs directory.
 
 .. code-block:: bash
 
     git-repo-name/
     │
     ├── docs/
-    │   └── index.rst
+    │   ├── index.rst
+    │   └── release-notes.rst
     │
     ├── helloworld-package/
     │   │
@@ -392,17 +397,17 @@ cannot upload the same package twice.
     │   └── tox.ini
     │
     ├── releases/
-    │   └── release-helloworld.yaml
+    │   └── pypi-helloworld.yaml
     │
     ├── .gitignore
     ├── LICENSE
     └── README.md
 
 
-Use of these templates requires a .pypirc configuration file in the
-Jenkins builder home directory. An example appears next that uses API
-tokens. Note that in the [pypi] entry the repository key-value pair is
-optional, it defaults to pypi.org.
+Jobs built from the PyPI templates depend on a .pypirc configuration file
+in the Jenkins builder home directory. An example appears next that uses
+API tokens. Note that in the [pypi] entry the repository key-value pair
+is optional, it defaults to pypi.org.
 
 .. code-block:: bash
 
@@ -434,6 +439,7 @@ optional, it defaults to pypi.org.
     :build-node: The node to run the build on.
     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
         in defaults.yaml)
+    :mvn-settings: The settings file with credentials for the project
     :project: Git repository name
     :project-name: Jenkins job name prefix
 
@@ -448,6 +454,9 @@ optional, it defaults to pypi.org.
     :disable-job: Whether to disable the job (default: false)
     :dist-binary: Whether to build a binary wheel distribution. (default: true)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+    :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
+    :mvn-params: Parameters to pass to the mvn CLI. (default: '')
+    :mvn-version: Version of maven to use. (default: mvn35)
     :parallel: Boolean indicator for tox to run tests in parallel or series.
        (default: false, in series)
     :pre-build-script: Shell script to execute before the tox builder. For
@@ -507,6 +516,7 @@ pyenv variables before running.
     :build-node: The node to run the build on.
     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
         in defaults.yaml)
+    :mvn-settings: The settings file with credentials for the project
     :project: Git repository name
     :project-name: Jenkins job name prefix
 
@@ -518,6 +528,9 @@ pyenv variables before running.
     :disable-job: Whether to disable the job (default: false)
     :dist-binary: Whether to build a binary wheel distribution. (default: true)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+    :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
+    :mvn-params: Parameters to pass to the mvn CLI. (default: '')
+    :mvn-version: Version of maven to use. (default: mvn35)
     :parallel: Boolean indicator for tox to run tests in parallel or series.
        (default: false, in series)
     :pre-build-script: Shell script to execute before the tox builder. For