spring-projects / spring-projects/spring-security

Update documentation of sample apps

Open
#8,190 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

in: docs type: enhancement
Dominant language
Java
Stars
9.6k
Forks
6.3k
Avg merge
2d 11h
Merged PRs (30d)
52

Description

Chapter 7 Samples is quite lite on content, it just links to the samples directory on git repo. I propose adding the following sections to the Samples chapter.

  • A short overview section describing what samples exist in the samples/ project
  • Sample apps directory with an entry for each sample app.

This would have an entry for each sample app should include

  • a short 1 to 3 sentence description of what the sample app demonstrates, so that users can quickly find an example of what they are looking to do.
  • a link to the sample application source code to easily find the code

The samples directory can be nicely organized along into category to make discovery easier. Suggested categories are.

  • Servlets
    • Web Authentication
    • Web Authorization
    • Method Security
  • Reactive
    • Web Authentication
    • Web Authorization
    • Method Security

It is possible to generate the content for such a directory automatically, below are some approaches.

buildfile approach Each samples gradle build file can define a gradle task to write out an summary.adoc file, then the parent project can iterate the child projects call each of the generate summary tasks, and collect all the output into the summary chapter. With this approach as the samples are updated summary directory gets generated.

description.md approach each samples gets a new file called description.md or description.adoc that can be included from the samples chapter.

The build file approach can more easily tag and category the samples, and potentially can be leveraged to drop references to sample apps in different sections of the docs.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Chapter 7 Samples documentation and the samples/ project referenced in the issue. Review the sample applications and their Gradle build files, then choose between generated summary.adoc files and per-sample description.md or description.adoc files. Done means the Samples chapter has an overview, categorized entries, descriptions, and source links for each sample.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.