Skip to content

Add docs outline with Antora skeleton #554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 7, 2022
Merged

Add docs outline with Antora skeleton #554

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
package-lock.json
node_modules
11 changes: 11 additions & 0 deletions docs/antora.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
name: reference
version: 0.2.2
prerelease: '-SNAPSHOT'

title: Spring Authorization Server
display_version: latest
start_page: ROOT:index.adoc
nav:
- modules/ROOT/nav.adoc
- modules/guides/nav.adoc
- modules/appendix/nav.adoc
16 changes: 16 additions & 0 deletions docs/local-antora-playbook.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
site:
title: Spring Authorization Server
url: https://docs.spring.io/spring-authorization-server
start_page: reference::index.adoc
asciidoc:
attributes:
page-pagination: true
content:
sources:
- url: ../
branches: [guides]
start_path: docs
ui:
bundle:
url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip
snapshot: true
7 changes: 7 additions & 0 deletions docs/modules/ROOT/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
.xref:index.adoc[Reference Manual]
* xref:overview.adoc[Overview]
* xref:getting-help.adoc[Getting Help]
* xref:getting-started.adoc[Getting Started]
* xref:configuration-model.adoc[Configuration Model]
* xref:core-components.adoc[Core Components]
* xref:protocol-endpoints.adoc[Protocol Endpoints]
18 changes: 18 additions & 0 deletions docs/modules/ROOT/pages/configuration-model.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
= Configuration Model

This page is under construction.

[[oauth2-authorization-server-configurer]]
== `OAuth2AuthorizationServerConfigurer`

This section is under construction.

[[oauth2-authorization-server-configuration]]
== `OAuth2AuthorizationServerConfiguration`

This section is under construction.

[[provider-settings]]
== `ProviderSettings` / `ProviderContext`

This section is under construction.
28 changes: 28 additions & 0 deletions docs/modules/ROOT/pages/core-components.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
= Core Components

This page is under construction.

[[registered-client-repository]]
== `RegisteredClientRepository` / `RegisteredClient`

This section is under construction.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Buzzardo Is this the appropriate wording to use for TODO sections?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading is a problem. With only the two object names, there is no indication of what you are going to say about them. Should it be "Using RegisteredClientRepository and RegisteredClient" or "Choosing between RegisteredClientRepository and RegisteredClient"?

Note that, in either case, I replaced the slash with "and". We see a slash used that way all the time in informal documents (email and so on), but using a slash in place of a conjunction is bad practice in formal documents (as all documentation is).

The "under construction" wording is fine. Would it be better to not show pages that have no content, though?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Buzzardo, regarding showing no-content pages, I'm hoping to begin linking between sections of the guide based on your recommendation to link early, link often 😉 (even before the sections are finished). While some things will change, I'm hoping we can create some semblance of structure prior to writing the content for each section.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding the headings, I agree and think we can meet to discuss good headings for these sections in the coming weeks. In the meantime, I'm going to go ahead and merge what I've got here to just match the initial draft outline, and we'll address this iteratively.


[[oauth2-authorization-service]]
== `OAuth2AuthorizationService` / `OAuth2Authorization`

This section is under construction.

[[oauth2-authorization-consent-service]]
== `OAuth2AuthorizationConsentService` / `OAuth2AuthorizationConsent`

This section is under construction.

[[jwt-encoder]]
== `JwtEncoder`

This section is under construction.

[[oauth2-token-customizer]]
== `OAuth2TokenCustomizer` / `OAuth2TokenContext`

This section is under construction.
3 changes: 3 additions & 0 deletions docs/modules/ROOT/pages/getting-help.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
= Getting Help

This page is under construction.
18 changes: 18 additions & 0 deletions docs/modules/ROOT/pages/getting-started.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
= Getting Started

This page is under construction.

[[system-requirements]]
== System Requirements

This section is under construction.

[[installing-spring-authorization-server]]
== Installing Spring Authorization Server

This section is under construction.

[[developing-your-first-application]]
== Developing Your First Spring Authorization Server Application

This section is under construction.
3 changes: 3 additions & 0 deletions docs/modules/ROOT/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
= Reference Manual

This page is under construction.
13 changes: 13 additions & 0 deletions docs/modules/ROOT/pages/overview.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
= Overview

This page is under construction.

[[introducing-spring-authorization-server]]
== Introducing Spring Authorization Server

This section is under construction.

[[feature-list]]
== Feature List

This section is under construction.
48 changes: 48 additions & 0 deletions docs/modules/ROOT/pages/protocol-endpoints.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
= Protocol Endpoints

This page is under construction.

[[oauth2-authorization-endpoint]]
== OAuth 2.0 Authorization Endpoint

This section is under construction.

[[oauth2-token-endpoint]]
== OAuth 2.0 Token Endpoint

This section is under construction.

[[oauth2-token-introspection-endpoint]]
== OAuth 2.0 Token Introspection Endpoint

This section is under construction.

[[oauth2-token-revocation-endpoint]]
== OAuth 2.0 Token Revocation Endpoint

This section is under construction.

[[oauth2-authorization-server-metadata-endpoint]]
== OAuth 2.0 Authorization Server Metadata Endpoint

This section is under construction.

[[jwk-set-endpoint]]
== JWK Set Endpoint

This section is under construction.

[[openid-connect-provider-configuration-endpoint]]
== OpenID Connect 1.0 Provider Configuration Endpoint

This section is under construction.

[[openid-connect-user-info-endpoint]]
== OpenID Connect 1.0 UserInfo Endpoint

This section is under construction.

[[openid-connect-client-registration-endpoint]]
== OpenID Connect 1.0 Client Registration Endpoint

This section is under construction.
1 change: 1 addition & 0 deletions docs/modules/appendix/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* xref:index.adoc[Appendices]
3 changes: 3 additions & 0 deletions docs/modules/appendix/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
= Appendices

This page is under construction.
2 changes: 2 additions & 0 deletions docs/modules/guides/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
.xref:index.adoc["How-to" Guides]
* xref:page-1.adoc[Example 1]
28 changes: 28 additions & 0 deletions docs/modules/guides/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
= "How-to" Guides

This page is under construction.

== Table of contents

** Obtain an access token using a specific grant_type:
*** `authorization_code`
*** `client_credentials`
*** `refresh_token`
** Customize form based login
** Authenticate a user with two-factor authentication
** Customize the user consent page
** Authenticate using OpenID Connect 1.0 authorization_code flow
** Customize the OpenID Connect 1.0 UserInfo response
** Authenticate using social login, e.g. Google
** Authenticate a user in a Single Page Application with PKCE
** Customize client authentication for specific authentication methods
** Handle errors and customize the OAuth 2.0 Error response
** Authorize an access token containing custom authorities, e.g. roles, groups, permissions, etc.
*** Customize the headers / claims in a JWT
** Deny access for a revoked JWT access token
*** Introspect / revoke an access token
** Provide a JWK source backed by a key rotation strategy
** Implement the core services with JPA:
*** `RegisteredClientRepository`
*** `OAuth2AuthorizationService`
*** `OAuth2AuthorizationConsentService`
1 change: 1 addition & 0 deletions docs/modules/guides/pages/page-1.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
= Example 1
6 changes: 6 additions & 0 deletions docs/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"dependencies": {
"@antora/cli": "^3.0.0-alpha.8",
"@antora/site-generator-default": "^3.0.0-alpha.8"
}
}