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

Migrate content to codebase and change Sphinx theme to Furo #61

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

activus-d
Copy link
Collaborator

No description provided.

Copy link

codecov bot commented Mar 4, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.0%. Comparing base (3ad1e62) to head (d37ccd6).
Report is 10 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #61   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files          13       13           
  Lines         720      720           
  Branches       59       59           
=======================================
  Hits          720      720           

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

🚀 New features to boost your workflow:
  • Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@activus-d activus-d requested a review from Stormheg March 5, 2025 00:00
… Furo

[pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

add sphinx_design and sphinx_copybutton to pyproject.toml and update development.md to indicate sphinx theme change

improve grammar and consistency in format of style guide

improve table
Copy link
Member

@Stormheg Stormheg left a comment

Choose a reason for hiding this comment

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

Thanks Damilola - documentation is turning out nicely.

Made a first pass.

Contributing
============

This package is open source and is licensed under the BSD-3 Clause `License <https://github.com/Stormbase/django-otp-webauthn/blob/main/LICENSE>`_. We welcome all contributions, including code improvements, bug fixes, and documentation updates.
Copy link
Member

Choose a reason for hiding this comment

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

Suggestion (non-blocking): how about we open the scope up a bit?

Suggested change
This package is open source and is licensed under the BSD-3 Clause `License <https://github.com/Stormbase/django-otp-webauthn/blob/main/LICENSE>`_. We welcome all contributions, including code improvements, bug fixes, and documentation updates.
This package is open source and is licensed under the BSD-3 Clause `License <https://github.com/Stormbase/django-otp-webauthn/blob/main/LICENSE>`_. We welcome all contributions, including translations, bug reports, tutorials, code improvements, and documentation updates.


5. Submit a pull request using your newly created branch.

6. Ensure your pull request has a clear and detailed description of the changes and include a link to the previously opened issue.
Copy link
Member

Choose a reason for hiding this comment

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

Follow-up (non-blocking): how about we set up issue report templates?

Copy link
Collaborator Author

@activus-d activus-d Mar 12, 2025

Choose a reason for hiding this comment

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

Check out this issue template that I created for the Canonical Ubuntu Server docs repository. Let me know if you like it. You can also suggest ways you think we can improve it.

.. code-block:: console

caddy trust

Copy link
Member

Choose a reason for hiding this comment

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

Suggestion: What about running the tests? Creating new translations?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@Stormheg I can't find the instructions on creating new translations in the README.md and DEVELOPMENT.md files

Words to avoid
--------------

Avoid informal or unclear words. Use the following table for guidance:
Copy link
Member

Choose a reason for hiding this comment

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

Suggestion: how about we explicitly list (internet) slang as something to avoid and add some examples?

ymmv -> you may not see the same results

u need to download Python -> you need to download Python

+----------------+---------------------------------------------------------+
| does not yet | doesn’t |
+----------------+---------------------------------------------------------+
| e.g. | for example or such as |
Copy link
Member

Choose a reason for hiding this comment

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

Suggestion: we should make clear why we avoid latin acronyms? Link to the relevant page in the Google Styleguide?

WebAuthn credential
A term defined in the Web Authentication specification. It's a key-based credential generated during a WebAuthn registration process, consisting of a public-private :term:`key pair`. The private key is securely stored on the user's device, while the public key is stored on the server for verifying future authentications.

This should not be confused with the WebAuthnCredential model, which only stores the public key and associated metadata.
Copy link
Member

Choose a reason for hiding this comment

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

Good opportunity for a link to the WebAuthnCredential reference page?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Are you suggesting that we create a reference page for WebAuthnCredential?
Currently, we have 4 pages in the Reference section:

  1. Views
  2. Helper
  3. Models
  4. JSON request and response


{% load otp_webauthn %}
* **Batteries:** Comes with a default frontend JavaScript implementation that works out of the box.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
* **Batteries:** Comes with a default frontend JavaScript implementation that works out of the box.
* **Frontend included:** Comes with a default frontend JavaScript implementation that works out of the box.

Copy link
Member

Choose a reason for hiding this comment

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

Decided I don't want to claim 'batteries included' anymore, figurative speech

<div id="passkey-register-status-message"></div>
</div>
</template>
* **Flexible frontend:** Users can customize the default UI to match their brand or implement a fully custom frontend.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
* **Flexible frontend:** Users can customize the default UI to match their brand or implement a fully custom frontend.
* **Flexible frontend:** Developers can style the provided user interface to match their brand or implement a fully custom frontend using the provided api views

Comment on lines +1 to +2
Limitations
===========
Copy link
Member

Choose a reason for hiding this comment

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

Issue: I don't like the term 'limitations', why not frequently answered questions?

Copy link
Collaborator Author

@activus-d activus-d Mar 12, 2025

Choose a reason for hiding this comment

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

Perhaps we should suggest a different title that sounds more positive. FAQs often feel like a sign of missing documentation or uncertainty, which doesn’t reflect well on the project and the documentation.

"github_type": "star",
"github_user": "Stormbase",
"github_repo": "django-otp-webauthn",
"source_repository": "https://github.com/Stormbase/django-otp-webauthn",
Copy link
Member

Choose a reason for hiding this comment

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

Feel free to update the copyright as well

@Stormheg
Copy link
Member

Stormheg commented Mar 8, 2025

@activus-d I presume it is not possible to bring the GitHub stargazer count back?

@activus-d
Copy link
Collaborator Author

GitHub stargazer count

The GitHub stargazer count isn’t a built-in feature of the Furo Sphinx theme. If we want to bring it back, we have to implement a custom solution.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

2 participants