Recent commits to derivepassphrase.git (f4ad50268204dc42eeb01e287a97eb1e9f8f599c)

Merge topic branch 'documentation-fixes' into master

2024-09-29T23:58:09+02:00

* t/documentation-fixes:
  Add changelog entry for recent documentation fixes
  Generate nicer documentation via `scoped_crossrefs`
  Convert old syntax for Yields annotations to new syntax
  Enable cross-references on function signatures in documentation
  Fix bad docstring reference to Python standard library
  Rename reference documentation pages as per the Python standard library convention
  Update all URLs to stable and "less legally risky" versions, if possible
  Demonstrate config storing and SSH agent use in README
  Include explanation for virtual environments and package extras in README
  Fix miscellaneous small docstring issues
</pre>

Add changelog entry for recent documentation fixes

2024-09-29T23:57:51+02:00

</pre>

Generate nicer documentation via `scoped_crossrefs`

2024-09-29T23:27:27+02:00

Now that (some) versions of `mkdocstrings-python` have support for
[scoped crossreferences] [SCOPED], references to documented objects can
be named like they would be in code.  This leads to (Markdown)
docstrings that are much more readable in source form than when having
to type or re-type the fully qualified identifier name.

[SCOPED]: https://github.com/mkdocstrings/python/issues/166
</pre>

Convert old syntax for Yields annotations to new syntax

2024-09-29T23:21:09+02:00

[Griffe now handles non-multiple yields and returns similarly.] [YIELDS]
There is thus no need for an empty argument name and type annotation.

[YIELDS]: https://github.com/mkdocstrings/griffe/issues/263
</pre>

Enable cross-references on function signatures in documentation

2024-09-29T23:17:02+02:00

When enabling `signature_crossrefs`, some default values use enumeration
values that we'd really like to have anchors for in the documentation.
(This also seems sensible for typing-only classes.)  We currently use an
"attributes" table in the class docstring for this purpose; build on
this by forcing MkDocs to render the respective class attribute too, via
an empty "docstring" for the attribute.

I considered enabling parameter headings, but these cannot be suppressed
from the table of contents, and the table of contents then starts
looking very cramped.
</pre>

Fix bad docstring reference to Python standard library

2024-09-28T09:10:01+02:00

</pre>

Reintegrate branch 'master' into documentation-fixes

2024-09-27T22:33:03+02:00

* master:
  Fix outstanding formatting and linting issues
  Switch from towncrier to scriv for changelog management
  Add changelog entry for hypothesis use
  Add hypothesis-based tests (and bugfix) for the vault derivation scheme
  Set up the "hypothesis" testing library
</pre>

Fix outstanding formatting and linting issues

2024-09-27T22:18:46+02:00

</pre>

Merge topic branch 'remove-towncrier' into master

2024-09-27T22:15:41+02:00

* t/remove-towncrier:
  Switch from towncrier to scriv for changelog management
</pre>

Switch from towncrier to scriv for changelog management

2024-09-27T21:35:32+02:00

I have found towncrier to be rather painful when used together with
Markdown entries: it feels very much like a reStructuredText-only tool
retrofitted with patchy Markdown support.  In particular, towncrier
blindly concatenates all entries (assumed to be list items) into the
output (and adds the implied issue links afterwards), manually adjusted
for nicer indentation in an ad-hoc fashion.  This fails horribly if the
changelog entry is anything except a single, paragraph-free list item;
it fails in particular for reference-style links and for multi-paragraph
entries.

So switch to scriv, by Ned Batchelder, which is a similar style to
towncrier.  That too has its issues, such as the automatically
generated, non-configurable HTML4-style heading anchor, but it's
somewhat more tolerant/encouraging of manual editing of the changelog
entries and the changelog master file.

Since we're cleaning up the changelog, use this opportunity to fix the
formatting of the existing entries.
</pre>