Skip to content
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.

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

website/developer-docs: add a baby Style Guide #9900

Merged
merged 18 commits into from
Jun 13, 2024
Merged

website/developer-docs: add a baby Style Guide #9900

merged 18 commits into from
Jun 13, 2024

Conversation

tanberry
Copy link
Contributor

@tanberry tanberry commented May 29, 2024

This new Style Guide covers most of the basics that I often edit in contributions. We need to increase awareness of the Style Guide; in a subsequent PR I will add links to it in other places.

  • The documentation has been updated
  • The documentation has been formatted (make website)

@tanberry tanberry requested a review from a team as a code owner May 29, 2024 03:29
Copy link

netlify bot commented May 29, 2024

Deploy Preview for authentik-storybook canceled.

Name Link
🔨 Latest commit 232e90d
🔍 Latest deploy log https://app.netlify.com/sites/authentik-storybook/deploys/666a21e2e955040008546829

Copy link

netlify bot commented May 29, 2024

Deploy Preview for authentik-docs ready!

Name Link
🔨 Latest commit 232e90d
🔍 Latest deploy log https://app.netlify.com/sites/authentik-docs/deploys/666a21e269f1ce0008c0a093
😎 Deploy Preview https://deploy-preview-9900--authentik-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@tanberry tanberry requested review from a team and removed request for a team May 29, 2024 03:30
Copy link

codecov bot commented May 29, 2024

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.64%. Comparing base (211cdb3) to head (232e90d).
Report is 127 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff            @@
##             main    #9900    +/-   ##
========================================
  Coverage   92.64%   92.64%            
========================================
  Files         710      713     +3     
  Lines       34744    34894   +150     
========================================
+ Hits        32188    32327   +139     
- Misses       2556     2567    +11     
Flag Coverage Δ
e2e 49.63% <ø> (-0.04%) ⬇️
integration 25.47% <ø> (-0.03%) ⬇️
unit 90.11% <ø> (+0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

website/developer-docs/docs/style-guide.mdx Outdated Show resolved Hide resolved
website/developer-docs/docs/style-guide.mdx Outdated Show resolved Hide resolved
website/developer-docs/docs/writing-documentation.md Outdated Show resolved Hide resolved
website/developer-docs/docs/writing-documentation.md Outdated Show resolved Hide resolved
website/integrations/template/service.md Outdated Show resolved Hide resolved
@tanberry tanberry requested a review from BeryJu May 30, 2024 18:57

## Integration guidelines
Whenever possible, use one of our [docs templates](./templates/index.md). This makes it a lot easier for you (no blank page frights!) and keeps the documentation consistent.
Copy link
Contributor

Choose a reason for hiding this comment

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

Shouldn't the singular of "docs" be used?


You can do local builds of the documentation to test your changes or review your new content, and to run the required `prettier` and linters before pushing your PR.

The documentation site is situated in the `/website` folder of the repo.
Copy link
Contributor

Choose a reason for hiding this comment

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

Use website/ instead of /website because website/ indicates a relative path within the repository, while /website suggests an absolute path from the root directory.

Copy link
Contributor Author

@tanberry tanberry Jun 12, 2024

Choose a reason for hiding this comment

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

Ah, this is a topic I have often discussed/debated. :-) I do actually intend it to be shown as an absolute path from the root dir. If they start at root, I want them to know what dir to look for from there.

True there are relative paths after/within website, but it's finding the top-level dir I want to focus on. Make sense?

website/developer-docs/docs/writing-documentation.md Outdated Show resolved Hide resolved
website/developer-docs/docs/style-guide.mdx Outdated Show resolved Hide resolved
website/developer-docs/docs/style-guide.mdx Outdated Show resolved Hide resolved
Copy link
Contributor

github-actions bot commented Jun 11, 2024

authentik PR Installation instructions

Instructions for docker-compose

Add the following block to your .env file:

AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-ghcr.io/goauthentik/dev-server:gh-232e90de1e2a256930b45911802e5f9456838033
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s

For arm64, use these values:

AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-ghcr.io/goauthentik/dev-server:gh-232e90de1e2a256930b45911802e5f9456838033-arm64
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s

Afterwards, run the upgrade commands from the latest release notes.

Instructions for Kubernetes

Add the following block to your values.yml file:

authentik:
    outposts:
        container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
image:
    repository: ghcr.io/goauthentik/dev-server
    tag: gh-ghcr.io/goauthentik/dev-server:gh-232e90de1e2a256930b45911802e5f9456838033

For arm64, use these values:

authentik:
    outposts:
        container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
image:
    repository: ghcr.io/goauthentik/dev-server
    tag: gh-ghcr.io/goauthentik/dev-server:gh-232e90de1e2a256930b45911802e5f9456838033-arm64

Afterwards, run the upgrade commands from the latest release notes.

Copy link
Contributor

@kensternberg-authentik kensternberg-authentik left a comment

Choose a reason for hiding this comment

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

Just bein' nitpicky. :-)

@@ -28,48 +31,27 @@ The site is built using npm, below are some useful make commands:
For real time viewing of changes, as you make them.

:::info
Be sure to run the formatter before committing changes.
Be sure to run a formatting command before committing changes.
Copy link
Contributor

Choose a reason for hiding this comment

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

"... the formatting command..." We have specific formatting commands:

  • make lint-fix (for Django)
  • make lint (for Go and for other Python sources)
  • cd web ; npm run prettier (for the WebUI)
  • cd website; npm run prettier (for the web docs)

Copy link
Contributor

Choose a reason for hiding this comment

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

It's possible I misunderstand the purpose of this document. For our product documentation (./website/), we have the npm run prettier command which will format your documents for you. (I'm surprised we don't run codespell or any other spell-check in there.). We have tools to enforce styling, and we should use more of them.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yeah, about spell-check... I think we do run something, but whatever it is, is not as robust as what is in our final build pipeline! We will learn more soon, I hope. ;-)

@@ -121,6 +123,8 @@ This is documented in the [developer docs](./setup/frontend-dev-environment.md)

Contributions to the technical documentation are greatly appreciated. Open a PR if you have improvements to make or new content to add. If you have questions or suggestions about the documentation, open an Issue. No contribution is too small.

Please be sure to refer to our [Style Guide](../developer-docs/docs/style-guide.mdx) for the docs, and use a [template](./docs/templates/index.md) to make it easier for you. The style guidelines are also used for any Integrations documentation, and we have a template for Integrations as well, in our [Github repo](https://github.com/goauthentik/authentik) at `/website/integrations/_template/service.md`.
Copy link
Contributor

Choose a reason for hiding this comment

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

You use the phrase [docs template] in that link consistently up until this point. Why change?


Run this command before committing, to ensure consistent syntax, clean formatting, and verify links. Note that if the formatting command is not run, the build will fail with an error about linting.
Run the appropriate formatting command for your set up before committing, to ensure consistent syntax, clean formatting, and verify links. Note that if the formatting command is not run, the build will fail with an error about linting.
Copy link
Contributor

Choose a reason for hiding this comment

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

shouldn't "set up" be "setup"? What I saw online seems to point towards the second option

Copy link
Contributor

@4d62 4d62 left a comment

Choose a reason for hiding this comment

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

other than that, lgtm

@tanberry tanberry merged commit 8f82dac into main Jun 13, 2024
69 checks passed
@tanberry tanberry deleted the style-guide branch June 13, 2024 14:11
kensternberg-authentik added a commit that referenced this pull request Jun 13, 2024
* main: (2701 commits)
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083)
  web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079)
  web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078)
  web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080)
  web: bump braces from 3.0.2 to 3.0.3 in /web (#10077)
  website: bump braces from 3.0.2 to 3.0.3 in /website (#10076)
  web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075)
  core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
  rbac: filters: fix missing attribute for unauthenticated requests (#10061)
  tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067)
  providers/microsoft_entra: fix error when updating connection attributes (#10039)
  website/integrations: aws: fix about service link (#10062)
  translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060)
  core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046)
  core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047)
  ...
kensternberg-authentik added a commit that referenced this pull request Jun 13, 2024
* main: (1301 commits)
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083)
  web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079)
  web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078)
  web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080)
  web: bump braces from 3.0.2 to 3.0.3 in /web (#10077)
  website: bump braces from 3.0.2 to 3.0.3 in /website (#10076)
  web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075)
  core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
  rbac: filters: fix missing attribute for unauthenticated requests (#10061)
  tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067)
  providers/microsoft_entra: fix error when updating connection attributes (#10039)
  website/integrations: aws: fix about service link (#10062)
  translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060)
  core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046)
  core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047)
  ...
kensternberg-authentik added a commit that referenced this pull request Jun 13, 2024
* main: (320 commits)
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083)
  web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079)
  web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078)
  web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080)
  web: bump braces from 3.0.2 to 3.0.3 in /web (#10077)
  website: bump braces from 3.0.2 to 3.0.3 in /website (#10076)
  web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075)
  core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
  rbac: filters: fix missing attribute for unauthenticated requests (#10061)
  tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067)
  providers/microsoft_entra: fix error when updating connection attributes (#10039)
  website/integrations: aws: fix about service link (#10062)
  translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060)
  core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046)
  core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047)
  ...
kensternberg-authentik added a commit that referenced this pull request Jun 13, 2024
…ore-dual-select-uses-2

* web/revision/more-dual-select-uses: (320 commits)
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083)
  web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079)
  web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078)
  web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080)
  web: bump braces from 3.0.2 to 3.0.3 in /web (#10077)
  website: bump braces from 3.0.2 to 3.0.3 in /website (#10076)
  web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075)
  core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
  rbac: filters: fix missing attribute for unauthenticated requests (#10061)
  tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067)
  providers/microsoft_entra: fix error when updating connection attributes (#10039)
  website/integrations: aws: fix about service link (#10062)
  translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060)
  core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046)
  core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047)
  ...
kensternberg-authentik added a commit that referenced this pull request Jun 13, 2024
* main: (320 commits)
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083)
  web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079)
  web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078)
  web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080)
  web: bump braces from 3.0.2 to 3.0.3 in /web (#10077)
  website: bump braces from 3.0.2 to 3.0.3 in /website (#10076)
  web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075)
  core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
  rbac: filters: fix missing attribute for unauthenticated requests (#10061)
  tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067)
  providers/microsoft_entra: fix error when updating connection attributes (#10039)
  website/integrations: aws: fix about service link (#10062)
  translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060)
  core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046)
  core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047)
  ...
kensternberg-authentik added a commit that referenced this pull request Jun 13, 2024
* main: (138 commits)
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083)
  web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079)
  web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078)
  web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080)
  web: bump braces from 3.0.2 to 3.0.3 in /web (#10077)
  website: bump braces from 3.0.2 to 3.0.3 in /website (#10076)
  web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075)
  core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
  rbac: filters: fix missing attribute for unauthenticated requests (#10061)
  tests/e2e: docker-compose.yml: remove version element forgotten last time (#10067)
  providers/microsoft_entra: fix error when updating connection attributes (#10039)
  website/integrations: aws: fix about service link (#10062)
  translate: Updates for file locale/en/LC_MESSAGES/django.po in it (#10060)
  core: bump github.com/redis/go-redis/v9 from 9.5.2 to 9.5.3 (#10046)
  core: bump github.com/gorilla/websocket from 1.5.1 to 1.5.2 (#10047)
  ...
kensternberg-authentik added a commit that referenced this pull request Jun 13, 2024
* main:
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083)
  web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079)
  web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078)
  web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080)
  web: bump braces from 3.0.2 to 3.0.3 in /web (#10077)
  website: bump braces from 3.0.2 to 3.0.3 in /website (#10076)
  web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075)
  core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
kensternberg-authentik added a commit that referenced this pull request Jun 17, 2024
* main:
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  core: bump google-api-python-client from 2.132.0 to 2.133.0 (#10083)
  web: bump prettier from 3.3.1 to 3.3.2 in /tests/wdio (#10079)
  web: bump chromedriver from 125.0.3 to 126.0.0 in /tests/wdio (#10078)
  web: bump @sentry/browser from 8.8.0 to 8.9.1 in /web in the sentry group (#10080)
  web: bump braces from 3.0.2 to 3.0.3 in /web (#10077)
  website: bump braces from 3.0.2 to 3.0.3 in /website (#10076)
  web: bump braces from 3.0.2 to 3.0.3 in /tests/wdio (#10075)
  core: bump azure-identity from 1.16.0 to 1.16.1 (#10071)
kensternberg-authentik added a commit that referenced this pull request Jun 17, 2024
* dev: (335 commits)
  website/docs: release notes for 2024.6 (#9812)
  policies/reputation: save to database directly (#10059)
  providers/enterprise: import user/group data when manually linking objects (#10089)
  core, web: update translations (#10108)
  web: Add enterprise / FIPS notification to the AdminOverviewPage (#10090)
  core: bump github.com/getsentry/sentry-go from 0.28.0 to 0.28.1 (#10095)
  web: bump API Client version (#10107)
  admin: system api: do not show FIPS status if no valid license (#10091)
  root: add configuration option to enable fips (#10088)
  web: bump the sentry group across 1 directory with 2 updates (#10101)
  web: bump ts-pattern from 5.1.2 to 5.2.0 in /web (#10098)
  web: bump the storybook group across 1 directory with 7 updates (#10102)
  core: bump github.com/gorilla/websocket from 1.5.2 to 1.5.3 (#10103)
  core: bump pydantic from 2.7.3 to 2.7.4 (#10093)
  core: bump bandit from 1.7.8 to 1.7.9 (#10094)
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  ...
kensternberg-authentik added a commit that referenced this pull request Jun 17, 2024
* main: (196 commits)
  website/docs: release notes for 2024.6 (#9812)
  policies/reputation: save to database directly (#10059)
  providers/enterprise: import user/group data when manually linking objects (#10089)
  core, web: update translations (#10108)
  web: Add enterprise / FIPS notification to the AdminOverviewPage (#10090)
  core: bump github.com/getsentry/sentry-go from 0.28.0 to 0.28.1 (#10095)
  web: bump API Client version (#10107)
  admin: system api: do not show FIPS status if no valid license (#10091)
  root: add configuration option to enable fips (#10088)
  web: bump the sentry group across 1 directory with 2 updates (#10101)
  web: bump ts-pattern from 5.1.2 to 5.2.0 in /web (#10098)
  web: bump the storybook group across 1 directory with 7 updates (#10102)
  core: bump github.com/gorilla/websocket from 1.5.2 to 1.5.3 (#10103)
  core: bump pydantic from 2.7.3 to 2.7.4 (#10093)
  core: bump bandit from 1.7.8 to 1.7.9 (#10094)
  website/developer-docs: add a baby Style Guide (#9900)
  website/integrations: gitlab: update certificate key pair location and specify sha (#9925)
  root: handle asgi exception (#10085)
  website: bump prettier from 3.3.1 to 3.3.2 in /website (#10082)
  web: bump prettier from 3.3.1 to 3.3.2 in /web (#10081)
  ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants