Merge pull request #95 from speed47/autogenerated

chore: checks_basic: verify that autogenerated doc is up to date

.github/workflows/tests_basic.yml

@@ -4,12 +4,12 @@ on: [push, pull_request]
 
 jobs:
     test:
-        name: perlcritic, perltidy & shellcheck
+        name: perlcritic, perltidy, shellcheck, doc
         runs-on: ubuntu-20.04
         steps:
         - uses: actions/checkout@v2
         - name: install prerequisites
-          run: sudo apt update && sudo apt install -y shellcheck libperl-critic-perl perltidy
+          run: sudo ./bin/admin/packages-check.sh -i -d
           env:
             DEBIAN_FRONTEND: noninteractive
         - name: shellcheck
@@ -18,3 +18,14 @@ jobs:
           run: bin/dev/perl-critic.sh
         - name: perl tidy
           run: bin/dev/perl-tidy.sh test
+        - name: autogenerate documentation
+          run: make -C doc/sphinx autogenerated
+        - name: verify git diff
+          run: |
+            if [ "$(git diff --numstat | wc -l)" != 0 ]; then
+                git diff
+                echo
+                echo "Some autogenerated documentation files are not up to date." >&2
+                echo "Please run 'make -C doc/sphinx autogenerated' and commit the result." >&2
+                exit 1
+            fi

doc/sphinx/Makefile

@@ -10,7 +10,9 @@ BUILDDIR      = _build
 VERSION_FILES = conf.py installation/basic.rst
 VERSION      := $(shell perl -e 'require "../../lib/perl/OVH/Bastion.pm"; print $$OVH::Bastion::VERSION')
 
-all: plugins default
+all: autogenerated default
+
+autogenerated: plugins
 
 default: Makefile
 	@sed -i -e "s/__VERSION__/$(VERSION)/g" $(VERSION_FILES)
@@ -25,7 +27,7 @@ help:
 plugins:
 	@bash build-plugins-help.sh
 
-.PHONY: help Makefile plugins all
+.PHONY: help Makefile plugins all autogenerated default
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

doc/sphinx/build-plugins-help.sh

@@ -67,7 +67,7 @@ cat >>"$pluginindex" <<EOF
 
 EOF
 
-for section in $(find doc/sphinx/plugins -mindepth 1 -maxdepth 1 -type d)
+for section in $(find doc/sphinx/plugins -mindepth 1 -maxdepth 1 -type d | LC_ALL=C sort)
 do
     indexfile="$section/index.rst"
     section=$(basename "$section")
@@ -78,7 +78,7 @@ do
 .. toctree::
 
 EOF
-    for plugin in $(find doc/sphinx/plugins/$section -type f -name "*.rst" ! -name "index.rst" | sort)
+    for plugin in $(find doc/sphinx/plugins/$section -type f -name "*.rst" ! -name "index.rst" | LC_ALL=C sort)
     do
         echo "   $(basename $plugin .rst)" >> "$indexfile"
     done

doc/sphinx/plugins/index.rst

@@ -5,8 +5,8 @@ Bastion plugins
 .. toctree::
 
    admin/index.rst
+   group-aclkeeper/index.rst
    group-gatekeeper/index.rst
-   restricted/index.rst
    group-owner/index.rst
    open/index.rst
-   group-aclkeeper/index.rst
+   restricted/index.rst

doc/sphinx/plugins/open/clush.rst

@@ -24,7 +24,7 @@ Launch a remote command on several machines sequentially (clush-like)
 
 .. option:: --no-pause-on-failure   
 
-   Don't pause if the remote command doesn't return failed (returned != 0)
+   Don't pause if the remote command failed (returned exit code != 0)
 
 .. option:: --no-confirm            
 

doc/sphinx/plugins/open/index.rst

@@ -8,8 +8,8 @@ open plugins
    batch
    clush
    groupInfo
-   groupListPasswords
    groupList
+   groupListPasswords
    groupListServers
    help
    info

doc/sphinx/plugins/restricted/index.rst

@@ -6,16 +6,16 @@ restricted plugins
 
    accountAddPersonalAccess
    accountCreate
-   accountDelete
    accountDelPersonalAccess
+   accountDelete
    accountGeneratePassword
    accountGrantCommand
    accountInfo
+   accountList
    accountListAccesses
    accountListEgressKeys
    accountListIngressKeys
    accountListPasswords
-   accountList
    accountMFAResetPassword
    accountMFAResetTOTP
    accountModify

doc/sphinx/plugins/restricted/realmInfo.rst

@@ -3,7 +3,7 @@ realmInfo
 ==========
 
 Display information about a bastion realm
-==========================================
+=========================================
 
 
 .. admonition:: usage

doc/sphinx/plugins/restricted/selfAddPersonalAccess.rst

@@ -2,8 +2,8 @@
 selfAddPersonalAccess
 ======================
 
-Remove a personal server access from an account
-===============================================
+Add a personal server access on your account
+============================================
 
 
 .. admonition:: usage