Merge pull request #174 from creative-commoners/pulls/5.2/doclint

DOC Linting
silverstripe · Apr 9, 2024 · ead6822 · ead6822
2 parents f3047f5 + 39809c7
commit ead6822
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 13 deletions.
diff --git a/.doclintrc b/.doclintrc
@@ -0,0 +1 @@
+/docs/en/
diff --git a/README.md b/README.md
@@ -17,13 +17,13 @@ authenticators such as fingerprint scanners. More information on this can be fou
 
 ## Installation
 
-```sh
+```bash
 composer require silverstripe/webauthn-authenticator
 ```
 
 ## Documentation
 
-For detailed developer and CMS user documentation, see [the documentation readme](docs/en/readme.md).
+Read the [WebAuthn authenticator documentation](https://docs.silverstripe.org/en/optional_features/mfa/authentictors/webauthn).
 
 ## License
 

diff --git a/composer.json b/composer.json
@@ -18,6 +18,7 @@
     "require-dev": {
         "phpunit/phpunit": "^9.6",
         "squizlabs/php_codesniffer": "^3",
+        "silverstripe/documentation-lint": "^1",
         "silverstripe/standards": "^1",
         "phpstan/extension-installer": "^1.3"
     },
@@ -33,6 +34,11 @@
             "client/lang"
         ]
     },
+    "config": {
+        "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        }
+    },
     "minimum-stability": "dev",
     "prefer-stable": true
 }
diff --git a/docs/en/readme.md → docs/en/index.md b/docs/en/readme.md → docs/en/index.md
@@ -1,14 +1,24 @@
-# Developer documentation
+---
+title: WebAuthn Authenticator
+---
 
-## What is Web Authentication (WebAuthn)?
+# WebAuthn authenticator
+
+## Installation
+
+```bash
+composer require silverstripe/webauthn-authenticator
+```
+
+## What is web authentication (`WebAuthn`)?
 
 We use the [web-auth/webauthn-framework PHP library](https://github.com/web-auth/webauthn-framework) to provide support
 for the Web Authentication protocol:
 
 > Webauthn defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by
 > web applications, for the purpose of strongly authenticating users.
 
-This module is a SilverStripe wrapper for implementing this library, and provides the frontend UI components to work
+This module is a Silverstripe wrapper for implementing this library, and provides the frontend UI components to work
 with [the silverstripe/mfa module](https://github.com/silverstripe/silverstripe-mfa).
 
 For more information about WebAuthn, see [the Guide to Web Authentication](https://webauthn.guide/).
@@ -21,30 +31,30 @@ You can configure (or remove) the "help" links shown to users when the "Security
 option is shown in multi-factor authentication registration or verification flows by adjusting the user help link
 in configuration:
 
-```yaml
+```yml
 SilverStripe\WebAuthn\RegisterHandler:
   user_help_link: 'http://intranet.mycompany.com/help/how-to-use-mfa'
 ```
 
-### Authenticator Selection Criteria
+### Authenticator selection criteria
 
 The way the `Webauthn\AuthenticatorSelectionCriteria` instance is configured will define how appropriate authenticators
 are selected to participate in the creation operation of WebAuthn attestations. It has three settings, which are
 explained in [the MDN web docs for authenticatorSelection](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredentialCreationOptions/authenticatorSelection#Syntax).
 
-The SilverStripe WebAuthn module allows you to configure the `authenticatorAttachment` option, which is responsible
+The Silverstripe WebAuthn module allows you to configure the `authenticatorAttachment` option, which is responsible
 for determining whether single or cross-platform authenticators can be used in the registration operation. The default
 is that devices must be cross-platform (e.g. security keys) while single-platform devices (e.g. touch ID on mobile
 phones) are disabled. You can adjust this setting by configuring
-`SilverStripe\WebAuthn\RegisterHandler.authenticator_attachment` to use one of these options:
+[`RegisterHandler.authenticator_attachment`](api:SilverStripe\WebAuthn\RegisterHandler->authenticator_attachment) to use one of these options:
 
-* `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE`: allows either
-* `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM`: single-platform only
-* `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM `: cross-platform only
+- `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE`: allows either
+- `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM`: single-platform only
+- `AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM`: cross-platform only
 
 For more information, see [Authenticator Selection Criteria](https://github.com/web-auth/webauthn-framework/blob/v1.2/doc/webauthn/PublicKeyCredentialCreation.md#authenticator-selection-criteria)
 
-## Compatibility with Subsites
+## Compatibility with subsites
 
 This module is not recommended for use if your project has the [silverstripe/subsites](https://github.com/silverstripe/silverstripe-subsites) module installed.