diff --git a/doc/requirements.txt b/doc/requirements.txt index 564ba4ed1..e65f0fc56 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,6 +1,5 @@ sphinx==4.2.0 openstackdocstheme>=2.2.1,<=2.3.1 # Apache-2.0 -sphinxcontrib-spelling==7.3.2 # API Reference Guide os-api-ref>=1.5.0 # Apache-2.0 diff --git a/doc/source/conf.py b/doc/source/conf.py index a6c75e697..9760dd698 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -36,10 +36,14 @@ author = 'StarlingX' # ones. extensions = [ # 'openstackdocstheme', - 'sphinxcontrib.spelling', 'starlingxdocs_plus' ] +if tags.has('use_spellext'): + extensions.append('sphinxcontrib.spelling') + spelling_word_list_filename='spelling_wordlist.txt' + spelling_exclude_patterns=['developer_resources/Layered_Build_cn.rst'] + # Add any paths that contain templates here, relative to this directory. #templates_path = ['_templates'] @@ -59,8 +63,6 @@ master_doc = 'index' # Usually you set "language" from the command line for these cases. language = None -spelling_word_list_filename='spelling_wordlist.txt' - # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path . diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst index 7f6fd67b4..ef81d2375 100644 --- a/doc/source/contributor/doc_contribute_guide.rst +++ b/doc/source/contributor/doc_contribute_guide.rst @@ -330,7 +330,8 @@ Formatting checks .. begin-post-build-checks -After every successful build several quality checks are performed against the +You can build the HTML documentation locally using the ``tox -e docs`` command. +After every successful build, several quality checks are performed against the build HTML output. .. code-block:: none @@ -395,23 +396,24 @@ This sample shows three problems. https://docutils.sourceforge.io/docs/ref/rst/directives.html#include * - Substitution errors - Scans the output for potential unexpanded substitutions such as - ``|prod|`` and reports which files they were found in along with the + ``|prod|`` and reports which files they were found in, along with the offending lines of HTML. .. note:: This check cannot distinguish between a substitution and an ascii - output table where cells are not properly padded. In either case the + output table where cells are not properly padded. In either case, the problem needs to be fixed. + - As above, find the problem in the appropriate :file:`.rst` file by examining the :file:`.html` file reported. Look for ``||`` code exposed in the output. In the corresponding :file:`.rst`, find and correct the issue. .. hint:: - Substitions are not allowed in code blocks, :ref:, :doc:, + Substitutions are not allowed in code blocks, :ref:, :doc:, or within |RST| markup such as ``**``, ``*```, `````, and so on. - Substitions cannot be used in ASCII "picture" style tables. If you + Substitutions cannot be used in ASCII "picture" style tables. If you need a substitution in a table, use the ``.. list-table::`` format instead. @@ -456,12 +458,12 @@ not found* error. This indicates that the page may have moved or been deleted. **Logs** Non "OK" results such as *file not found* and *permanent redirect* are -logged under :file:`doc/builds/linkcheck` in two files: +logged under :file:`doc/build/linkcheck` in two files: -* :file:`doc/builds/linkcheck/output.txt` provides a results log in plain-text +* :file:`doc/build/linkcheck/output.txt` provides a results log in plain-text format. -* :file:`doc/builds/linkcheck/output.json` provides the same information in +* :file:`doc/build/linkcheck/output.json` provides the same information in ``JSON`` format. Investigate all issues and update the links as needed. In the case of permanent @@ -559,8 +561,9 @@ RST conventions --------------- StarlingX documentation follows many (but not all!) of the RST conventions -described in the `OpenStack documentation RST conventions guide `_. If RST markup is -not listed in this section's quick reference, refer to the OpenStack guide. +described in the `OpenStack documentation RST conventions guide +`_. If RST markup +is not listed in this section's quick reference, refer to the OpenStack guide. For detailed information about RST and Sphinx extensions, refer to the following documents: @@ -836,5 +839,6 @@ Example RST: Subsection heading ****************** - Integer sed tortor nisi. Vivamus feugiat, urna in posuere gravida, ligula nunc hendrerit magna, nec tristique ex tortor non lorem. + Integer sed tortor nisi. Vivamus feugiat, urna in posuere gravida, ligula + nunc hendrerit magna, nec tristique ex tortor non lorem. diff --git a/doc/source/spelling_wordlist.txt b/doc/source/spelling_wordlist.txt index 324cc4e09..5a7925703 100644 --- a/doc/source/spelling_wordlist.txt +++ b/doc/source/spelling_wordlist.txt @@ -1,17 +1,17 @@ -µs accessMode acmesolver addon addrpool +affined AIO AlarmID AlarmSeverity allowMultiplePerNode analytics -ansible Ansible -aodh +ansible Aodh +aodh api apiGroups apis @@ -27,10 +27,11 @@ authNoPriv authPriv autoboot autoscale -autoscaler Autoscaler +autoscaler autoscaling autounseal +Auth awk backend Backend @@ -43,15 +44,15 @@ billingDeptGroup bindDN bindep bindPW -bitbake Bitbake +bitbake bitstream blkin blockchain bmc boolean -bootable Bootable +bootable bootimage bootloader Broadcom @@ -66,8 +67,8 @@ ceph Ceph cephfs cephx -certifcate certtype +cfg cgroup cgroups cgts @@ -87,17 +88,17 @@ Coleto collectd Columbiaville commandline -config Config +config configmap configmaps configs ConnectX -containerd Containerd +containerd controllerstorage -coredns Coredns +coredns CoW cpio cpu @@ -118,8 +119,8 @@ cutover cyber Cygwin daemonset -Daemonsets daemonsets +Daemonsets datafile datanet datanetwork @@ -131,23 +132,23 @@ dcdbsync dcmanager dcorch dedicatedstorage -deprovision Deprovision +deprovision deprovisioned deprovisioning dev Dev devtoolset -dex Dex +dex distcloud -distro Distro +distro distros DL dns -dockerfile Dockerfile +dockerfile dpdk dpdkBasebandDevice dracut @@ -155,13 +156,13 @@ DRBD dropdown eASIC ebtables -edgeworker Edgeworker edgeworker +edgeworker Edgeworkers EF -efi EFI +efi Emulex enablement engineID @@ -172,13 +173,11 @@ etcd Etcd EtcdCA EtcdRootCA -etf eth ethernet EventID EventSeverity EventType -examplex eXtensible facto failover @@ -191,11 +190,10 @@ fieldname fileName filepath filestore -filesystem Filesystem +filesystem filesystems Filesystems -filesystems Fortville fqdn Freerun @@ -221,8 +219,8 @@ hardcode hardcoded hexidecimal hieradata -hostname Hostname +hostname hostnames hostwd hpa @@ -231,8 +229,8 @@ https hugepage hugepages Hugepages -hyperthreading Hyperthreading +hyperthreading hyperthreads hypervisor hypervisors @@ -252,7 +250,6 @@ initrd inprogress insync integ -intel intermediateCA intnet IoT @@ -267,8 +264,9 @@ isohybrid isolcpus javascript jetstack -kata +jsmith Kata +kata keypairs keystoneUserName KiB @@ -279,18 +277,18 @@ kubeadm kubeconfig kubectl kubelet -kubelets Kubelets -kubernetes +kubelets Kubernetes +kubernetes kubesystem kustomize kvm -libnetwork Libnetwork +libnetwork libvirt -lifecycle Lifecycle +lifecycle linters linux linuxptp @@ -299,6 +297,7 @@ loadbuild localdisk localhost localrc +login logrotate loopback losetup @@ -309,15 +308,15 @@ lvmthinpool macOS makefile managerGroup -mariadb Mariadb +mariadb Mbps Mellanox Memcached -mgmt Mgmt -mib +mgmt MiB +mib mins mitigations mkisofs @@ -333,8 +332,8 @@ mqprio msec mtcAgent mtu -multicast Multicast +multicast multichassis multus myApplication @@ -346,8 +345,8 @@ Namespace namespaced namespaces Namespaces -netapp Netapp +netapp Netapps netboot netdevice @@ -358,8 +357,8 @@ networktype newnote nfd nfv -nginx Nginx +nginx Niantic NIC nn @@ -374,12 +373,12 @@ numa numvfs nvidia nvme -oam OAM oam +oam OCI -oidc Oidc +oidc ok onboard Onboard @@ -393,23 +392,23 @@ Openssh openssl openstack Openstack -openstack openstackclients +Orchestrator +orchestrator osd overrideable ovs -ovverrides panko Panko Paravirtualized passhtru -passthrough Passthrough -pci +passthrough PCI +pci pciaddress -pcnet PCnet +pcnet peergroup pem persistentvolume @@ -418,22 +417,22 @@ pgp pgs phc pids -pkgs Pkgs +pkgs platformclients playbookconfig pmon pmond pnet podAntiAffinity -portieris Portieris +portieris portState -postgres Postgres +postgres Postgresql -postrequisites Postrequisites +postrequisites poweroff Powerville Pre @@ -441,13 +440,13 @@ pre preconfigured prepended prepends -prestage Prestage -prestaged +prestage Prestaged +prestaged Prestages -prestaging Prestaging +prestaging prestart ProbableCause processname @@ -455,17 +454,16 @@ project ProposedRepairAction Proto providernet -provisoner -provsioner -pruposes +Provisioner +provisioner psp ptp ptptracking pv pvc pxe -pxeboot Pxeboot +pxeboot pxebooting pxelinux py @@ -495,26 +493,28 @@ Realtek ReasonText rebase reconfig +Redfish +redfish redirectURIs redis rehome Rehome rehomed -rehoming Rehoming rehoming -reinstallation +reinstall Reinstallation +reinstallation reinstallations -Rendevous +reinstalled reno replicaCount replicaSet ReplicaSets repo -Repo -REPO repo +REPO +Repo Repo repo repos @@ -526,18 +526,18 @@ resourceName restapi reStructuredText retestneeded -retimer Retimer +retimer rgw -rk RK +rk rmdir -rolebindings RoleBindings +rolebindings rookstorage rootca -rootfs Rootfs +rootfs rootkey rpc rpmbuild @@ -556,6 +556,7 @@ rvmc Salesforce sampleimage sbin +scalable sched schemas sda @@ -563,69 +564,62 @@ sdb sdc secureboot sed -selectwhich sensorname -seperated serviceAccount serviceaccount serviceaccounts serviceAccounts ServiceAffecting severities -snmp SNMP snmp snmpd specfile spectre Spectre -spectre Springville -src Src +src sriov sRootCA srpm srpms SSD ssl -starlingx -Starlingx StarlingX +starlingx statefulset staticClients stdout storages -stx -Stx STX +Stx stx - Subcloud subcloud -subclouds Subclouds +subclouds subcommand -subcommands Subcommands +subcommands subfunctions subgit subinterface subnet Subnet subnetpool -subnets Subnets +subnets sudo sudoers SuppressionAllowed svc sw -swact Swact +swact Swacted -swacting Swacting +swacting Swacts SX Symkloud @@ -633,8 +627,8 @@ symlink symlinks synching sys -sysinv Sysinv +sysinv syslog systemController systemctl @@ -659,8 +653,8 @@ tls TLS tmp toml -Triaged triaged +Triaged triages triaging trustServer @@ -668,7 +662,6 @@ TSN tty tx Tx -tx txt udisksctl udp @@ -683,14 +676,13 @@ unixPermissions Unmanage unmanaged Unmanaged -unmanaged unmanaging Unmount unmounting Unpause unreferenced -unsuppress Unsuppress +unsuppress unsuppressing untrusted uptime @@ -698,8 +690,8 @@ upversion Upversion upversioned uri -Url url +Url urls useradd userid @@ -712,19 +704,18 @@ varbinds vdi Venafi vf -vfio Vfio vfio vfor vg -vhost Vhost +vhost Vid Vids virsh virt -virtio Virtio +virtio virtualized vlan Vlan @@ -734,16 +725,16 @@ volumegroup volumev vPC vRAN -vswitch vSwitch +vswitch VTx vxlan wadcert warmStart webhook Webhook -webserver Webserver +webserver wget windriver winpty @@ -760,4 +751,5 @@ yaml yml yums zoneinfo -zuul \ No newline at end of file +zuul +µs diff --git a/tox.ini b/tox.ini index c006087c7..c164109f3 100644 --- a/tox.ini +++ b/tox.ini @@ -58,6 +58,7 @@ commands = [testenv:spellcheck] deps = -r{toxinidir}/doc/requirements.txt + sphinxcontrib-spelling==7.3.2 commands = - sphinx-build -a -E -W --keep-going -d doc/build/doctrees -t starlingx -t openstack -b spelling doc/source doc/build/spelling {posargs} + sphinx-build -a -E --keep-going -d doc/build/doctrees -t starlingx -t openstack -t use_spellext -b spelling doc/source doc/build/spelling {posargs}