rtd¶

                                                                                
 Usage: lftools-uv rtd [OPTIONS] COMMAND [ARGS]...                              
                                                                                
 Read the Docs interface.                                                       
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ project-list              Get a list of Read the Docs projects.              │
│ project-details           Get details for a specific Read the Docs project.  │
│ project-create            Create a new Read the Docs project.                │
│ project-update            Update an existing Read the Docs project.          │
│ project-version-list      Retrieve the active versions of a project.         │
│ project-version-details   Retrieve details of a single version.              │
│ project-version-update    Update a version's active flag.                    │
│ project-build-list        Retrieve a project's running builds.               │
│ project-build-details     Retrieve the details of a specific build.          │
│ project-build-trigger     Trigger a build of a project version.              │
│ subproject-list           Get a list of subprojects for a project.           │
│ subproject-details        Retrieve the details of a specific subproject.     │
│ subproject-create         Create a project/subproject relationship.          │
│ subproject-delete         Delete a project/subproject relationship.          │
╰──────────────────────────────────────────────────────────────────────────────╯

Machine-readable output¶

Every command accepts --json and emits a parsable payload on stdout. Diagnostics go to stderr, so a caller may parse stdout without a warning corrupting the stream.

lftools-uv rtd project-version-details onap-cps latest --json | jq '.active'

The flag works before or after the subcommand:

lftools-uv rtd --json project-list
lftools-uv rtd project-list --json

Commands that return a collection always include the collection in the --json payload, empty when nothing matches, so a parser needs no special case for the empty result. Table output prints a short message such as No projects found instead.

Branch names and version slugs¶

Read the Docs addresses a version by its slug, which lowercases the branch name and replaces every character outside [a-z0-9._-] with a hyphen. Read the Docs holds a branch named maintenance/3.7.10 under the slug maintenance-3.7.10.

Passing a raw branch name to the API produces a request path that does not resolve. Commands that accept a version offer --from-branch, which performs the conversion:

lftools-uv rtd project-build-trigger onap-cps maintenance/3.7.10 --from-branch

Omit the flag when you already hold a slug.

Commands¶

project-list¶

                                                                                
 Usage: lftools-uv rtd project-list [OPTIONS]                                   
                                                                                
 Get a list of Read the Docs projects.                                          
                                                                                
 Returns projects by their slug name, not their pretty name, since the slug is  
 what other commands accept.                                                    
                                                                                
 Examples: lftools-uv rtd project-list lftools-uv rtd project-list --json       
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

project-details¶

                                                                                
 Usage: lftools-uv rtd project-details [OPTIONS] {project_slug}                 
                                                                                
 Get details for a specific Read the Docs project.                              
                                                                                
 Examples: lftools-uv rtd project-details onap-cps lftools-uv rtd               
 project-details onap-cps --json                                                
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug      <str>  Project slug name                              │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

project-create¶

                                                                                
 Usage: lftools-uv rtd project-create [OPTIONS] {project_name} {repository_url} 
                                      {repository_type} {homepage}              
                                      {programming_language} {language}         
                                                                                
 Create a new Read the Docs project.                                            
                                                                                
 Examples: lftools-uv rtd project-create onap-cps https://example.org/cps git   
 https://onap-cps.readthedocs.io py en                                          
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_name              <str>  Project name                           │
│                                       [required]                             │
│ *    repository_url            <str>  Repository URL                         │
│                                       [required]                             │
│ *    repository_type           <str>  Repository type: git, hg, bzr or svn   │
│                                       [required]                             │
│ *    homepage                  <str>  Project homepage URL                   │
│                                       [required]                             │
│ *    programming_language      <str>  Programming language abbreviation,     │
│                                       e.g. py                                │
│                                       [required]                             │
│ *    language                  <str>  Two-letter language code, e.g. en      │
│                                       [required]                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

project-update¶

                                                                                
 Usage: lftools-uv rtd project-update [OPTIONS] {project_slug}                  
                                                                                
 Update an existing Read the Docs project.                                      
                                                                                
 Accepts any number of key=value pairs matching the fields the Read the Docs    
 API allows.                                                                    
                                                                                
 Examples: lftools-uv rtd project-update onap-cps default_version=latest        
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug      <str>  Project slug name                              │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

project-version-list¶

                                                                                
 Usage: lftools-uv rtd project-version-list [OPTIONS] {project_slug}            
                                                                                
 Retrieve the active versions of a project.                                     
                                                                                
 Examples: lftools-uv rtd project-version-list onap-cps                         
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug      <str>  Project slug name                              │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

project-version-details¶

                                                                                
 Usage: lftools-uv rtd project-version-details [OPTIONS] {project_slug}         
                                               {VERSION_SLUG}                   
                                                                                
 Retrieve details of a single version.                                          
                                                                                
 Read the Docs addresses a version by its slug, so a branch named               
 maintenance/3.7.10 is stored as maintenance-3.7.10. Pass --from-branch to      
 convert a branch name automatically.                                           
                                                                                
 Examples: lftools-uv rtd project-version-details onap-cps latest lftools-uv    
 rtd project-version-details onap-cps maintenance/3.7.10 --from-branch          
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug      <str>  Project slug name                              │
│                               [required]                                     │
│ *    VERSION_SLUG      <str>  Version slug name                              │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --from-branch          Treat VERSION_SLUG as a git branch name and slugify   │
│                        it first.                                             │
│ --json                 Emit machine-readable JSON instead of a table.        │
│ --help                 Show this message and exit.                           │
╰──────────────────────────────────────────────────────────────────────────────╯

project-version-update¶

                                                                                
 Usage: lftools-uv rtd project-version-update [OPTIONS] {project_slug}          
                                              {VERSION_SLUG} {active}           
                                                                                
 Update a version's active flag.                                                
                                                                                
 Examples: lftools-uv rtd project-version-update onap-cps maintenance/3.7.10    
 true --from-branch                                                             
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug      <str>  Project slug name                              │
│                               [required]                                     │
│ *    VERSION_SLUG      <str>  Version slug name                              │
│                               [required]                                     │
│ *    active                   Whether the version should be active           │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --from-branch          Treat VERSION_SLUG as a git branch name and slugify   │
│                        it first.                                             │
│ --json                 Emit machine-readable JSON instead of a table.        │
│ --help                 Show this message and exit.                           │
╰──────────────────────────────────────────────────────────────────────────────╯

project-build-list¶

                                                                                
 Usage: lftools-uv rtd project-build-list [OPTIONS] {project_slug}              
                                                                                
 Retrieve a project's running builds.                                           
                                                                                
 With --json the payload always carries a builds list, empty when nothing is    
 running, so a caller can parse the result without a special case. Table output 
 prints a short message instead.                                                
                                                                                
 Examples: lftools-uv rtd project-build-list onap-cps --json                    
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug      <str>  Project slug name                              │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

project-build-details¶

                                                                                
 Usage: lftools-uv rtd project-build-details [OPTIONS] {project_slug}           
                                             {build_id}                         
                                                                                
 Retrieve the details of a specific build.                                      
                                                                                
 Examples: lftools-uv rtd project-build-details onap-cps 9584913 --json         
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug      <str>  Project slug name                              │
│                               [required]                                     │
│ *    build_id          <str>  Build identifier                               │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

project-build-trigger¶

                                                                                
 Usage: lftools-uv rtd project-build-trigger [OPTIONS] {project_slug}           
                                             {VERSION_SLUG}                     
                                                                                
 Trigger a build of a project version.                                          
                                                                                
 Examples: lftools-uv rtd project-build-trigger onap-cps latest lftools-uv rtd  
 project-build-trigger onap-cps maintenance/3.7.10 --from-branch                
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug      <str>  Project slug name                              │
│                               [required]                                     │
│ *    VERSION_SLUG      <str>  Version slug to build                          │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --from-branch          Treat VERSION_SLUG as a git branch name and slugify   │
│                        it first.                                             │
│ --json                 Emit machine-readable JSON instead of a table.        │
│ --help                 Show this message and exit.                           │
╰──────────────────────────────────────────────────────────────────────────────╯

subproject-list¶

                                                                                
 Usage: lftools-uv rtd subproject-list [OPTIONS] {project_slug}                 
                                                                                
 Get a list of subprojects for a project.                                       
                                                                                
 Examples: lftools-uv rtd subproject-list onap                                  
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug      <str>  Parent project slug name                       │
│                               [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

subproject-details¶

                                                                                
 Usage: lftools-uv rtd subproject-details [OPTIONS] {project_slug}              
                                          {subproject_slug}                     
                                                                                
 Retrieve the details of a specific subproject.                                 
                                                                                
 Examples: lftools-uv rtd subproject-details onap onap-cps --json               
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug         <str>  Parent project slug name                    │
│                                  [required]                                  │
│ *    subproject_slug      <str>  Subproject slug name                        │
│                                  [required]                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

subproject-create¶

                                                                                
 Usage: lftools-uv rtd subproject-create [OPTIONS] {project_slug}               
                                         {subproject_slug}                      
                                                                                
 Create a project/subproject relationship.                                      
                                                                                
 Examples: lftools-uv rtd subproject-create onap onap-cps                       
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug         <str>  Parent project slug name                    │
│                                  [required]                                  │
│ *    subproject_slug      <str>  Subproject slug name                        │
│                                  [required]                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --alias        <str>  Optional user-defined alias                            │
│ --json                Emit machine-readable JSON instead of a table.         │
│ --help                Show this message and exit.                            │
╰──────────────────────────────────────────────────────────────────────────────╯

subproject-delete¶

                                                                                
 Usage: lftools-uv rtd subproject-delete [OPTIONS] {project_slug}               
                                         {subproject_slug}                      
                                                                                
 Delete a project/subproject relationship.                                      
                                                                                
 Examples: lftools-uv rtd subproject-delete onap onap-cps                       
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    project_slug         <str>  Parent project slug name                    │
│                                  [required]                                  │
│ *    subproject_slug      <str>  Subproject slug name                        │
│                                  [required]                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Emit machine-readable JSON instead of a table.               │
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

Configuration¶

API requires a [rtd] section in ~/.config/lftools/lftools.ini:

[rtd]
token = REDACTED
endpoint = https://readthedocs.org/api/v3/