refactor: Rework public API and docs

.github/workflows/ci.yml

@@ -29,6 +29,9 @@ jobs:
     - name: Fetch all tags
       run: git fetch --depth=1 --tags
 
+    - name: Set up Graphviz
+      uses: ts-graphviz/setup-graphviz@v2
+
     - name: Set up Python
       uses: actions/setup-python@v5
       with:

CHANGELOG.md

@@ -53,10 +53,10 @@ We are still in v0, so no major bump yet.
 ### Deprecations
 
 - As seen above in the breaking changes section, the only parameters of [`Object.has_labels()`][griffe.Object.has_labels] and [`load_extensions()`][griffe.load_extensions] both became variadic positional parameters. Passing a sequence as single argument is deprecated in favor of passing multiple arguments. This is an ergonomic change: I myself often forgot to wrap extensions in a list. Passing sequences of labels (lists, sets, tuples) is also difficult from Jinja templates.
-- The following methods and properties on objects and aliases are deprecated: [`member_is_exported()`][griffe.Object.member_is_exported], [`is_explicitely_exported`][griffe.mixins.ObjectAliasMixin.is_explicitely_exported], [`is_implicitely_exported`][griffe.mixins.ObjectAliasMixin.is_implicitely_exported]. Use the [`is_exported`][griffe.mixins.ObjectAliasMixin.is_exported] property instead. See [issue 281](https://github.com/mkdocstrings/griffe/issues/281).
-- The [`is_exported()`][griffe.mixins.ObjectAliasMixin.is_exported] and [`is_public()`][griffe.mixins.ObjectAliasMixin.is_public] methods became properties. They can still be called like methods, but will emit deprecation warnings when doing so. See [issue 281](https://github.com/mkdocstrings/griffe/issues/281).
+- The following methods and properties on objects and aliases are deprecated: [`member_is_exported()`][griffe.Object.member_is_exported], [`is_explicitely_exported`][griffe.ObjectAliasMixin.is_explicitely_exported], [`is_implicitely_exported`][griffe.ObjectAliasMixin.is_implicitely_exported]. Use the [`is_exported`][griffe.ObjectAliasMixin.is_exported] property instead. See [issue 281](https://github.com/mkdocstrings/griffe/issues/281).
+- The [`is_exported()`][griffe.ObjectAliasMixin.is_exported] and [`is_public()`][griffe.ObjectAliasMixin.is_public] methods became properties. They can still be called like methods, but will emit deprecation warnings when doing so. See [issue 281](https://github.com/mkdocstrings/griffe/issues/281).
 - The `ignore_private` parameter of the [`find_breaking_changes()`][griffe.find_breaking_changes] function is now deprecated and unused. With the reworked "exported" and "public" API, this parameter became useless. See [issue 281](https://github.com/mkdocstrings/griffe/issues/281).
-- Using `stats()` instead of [`Stats`][griffe.stats.Stats] will now emit a deprecation warning.
+- Using `stats()` instead of [`Stats`][griffe.Stats] will now emit a deprecation warning.
 
 ### Features
 
@@ -487,8 +487,8 @@ We are still in v0, so no major bump yet.
 
 ### Breaking Changes
 
-- Removed `griffe.expressions.Expression` in favor of [`griffe.expressions.Expr`][] and subclasses
-- Removed `griffe.expressions.Name` in favor of [`griffe.expressions.ExprName`][]
+- Removed `griffe.expressions.Expression` in favor of [`griffe.Expr`][] and subclasses
+- Removed `griffe.expressions.Name` in favor of [`griffe.ExprName`][]
 
 ### Features
 
@@ -537,11 +537,11 @@ We are still in v0, so no major bump yet.
 
 ### Deprecations
 
-- Classes [`InspectorExtension`][griffe.extensions.base.InspectorExtension]
-    and [`VisitorExtension`][griffe.extensions.base.VisitorExtension]
-    are deprecated in favor of [`Extension`][griffe.extensions.base.Extension].
-    As a side-effect, the [`hybrid`][griffe.extensions.hybrid.HybridExtension] extension
-    is also deprecated. See [how to use and write extensions](extensions.md).
+- Classes [`InspectorExtension`][griffe.InspectorExtension]
+    and [`VisitorExtension`][griffe.VisitorExtension]
+    are deprecated in favor of [`Extension`][griffe.Extension].
+    As a side-effect, the [`hybrid`][griffe.HybridExtension] extension
+    is also deprecated. See [how to use and write extensions](guide/users/extending.md).
 
 ### Breaking Changes
 
@@ -554,7 +554,7 @@ We are still in v0, so no major bump yet.
 - Function `load_extension` was removed (made private)
 - Function `patch_ast` was removed
 - Function `tmp_worktree` was removed (made private)
-- Type [`Extension`][griffe.extensions.base.Extension] is now a class
+- Type [`Extension`][griffe.Extension] is now a class
 
 ### Features
 
@@ -590,11 +590,11 @@ We are still in v0, so no major bump yet.
 
 - Drop support for Python 3.7
 - API changes:
-    - [`GriffeLoader.resolve_aliases(only_exported)`][griffe.loader.GriffeLoader.resolve_aliases]: Deprecated parameter was removed and replaced by `implicit` (inverse semantics)
-    - [`GriffeLoader.resolve_aliases(only_known_modules)`][griffe.loader.GriffeLoader.resolve_aliases]: Deprecated parameter was removed and replaced by `external` (inverse semantics)
-    - [`LinesCollection.tokens`][griffe.collections.LinesCollection]: Public object was removed (Python 3.7)
+    - [`GriffeLoader.resolve_aliases(only_exported)`][griffe.GriffeLoader.resolve_aliases]: Deprecated parameter was removed and replaced by `implicit` (inverse semantics)
+    - [`GriffeLoader.resolve_aliases(only_known_modules)`][griffe.GriffeLoader.resolve_aliases]: Deprecated parameter was removed and replaced by `external` (inverse semantics)
+    - [`LinesCollection.tokens`][griffe.LinesCollection]: Public object was removed (Python 3.7)
     - `ASTNode.end_lineno`: Public object was removed (Python 3.7)
-    - [`griffe.agents.extensions`][griffe.agents] Deprecated module was removed and replaced by [`griffe.extensions`][]
+    - `griffe.agents.extensions`: Deprecated module was removed and replaced by `griffe.extensions`
 
 ### Features
 
@@ -863,9 +863,8 @@ We are still in v0, so no major bump yet.
 
 <small>[Compare with 0.24.1](https://github.com/mkdocstrings/griffe/compare/0.24.1...0.25.0)</small>
 
-### Breaking Changes
-
-- Parameter `only_known_modules` was renamed `external` in the [`expand_wildcards()`][griffe.loader.GriffeLoader.expand_wildcards] method of the loader.
+### Breaking changes
+- Parameter `only_known_modules` was renamed `external` in the [`expand_wildcards()`][griffe.GriffeLoader.expand_wildcards] method of the loader.
 - Exception `UnhandledEditablesModuleError` was renamed `UnhandledEditableModuleError` since we now support editable installation from other packages than `editables`.
 
 ### Highlights
@@ -921,18 +920,18 @@ for the initial code allowing to compare two Griffe trees.
 
 ### Breaking Changes
 
-- All parameters of the [`load_git`][griffe.loader.load_git] function, except `module`, are now keyword-only.
-- Parameter `try_relative_path` of the [`load_git`][griffe.loader.load_git] function was removed.
-- Parameter `commit` was renamed `ref` in the [`load_git`][griffe.loader.load_git] function.
+- All parameters of the [`load_git`][griffe.load_git] function, except `module`, are now keyword-only.
+- Parameter `try_relative_path` of the [`load_git`][griffe.load_git] function was removed.
+- Parameter `commit` was renamed `ref` in the [`load_git`][griffe.load_git] function.
 - Parameter `commit` was renamed `ref` in the `tmp_worktree` helper, which will probably become private later.
 - Parameters `ref` and `repo` switched positions in the `tmp_worktree` helper.
-- All parameters of the [`resolve_aliases`][griffe.loader.GriffeLoader.resolve_aliases] method are now keyword-only.
-- Parameters `only_exported` and `only_known_modules` of the [`resolve_module_aliases`][griffe.loader.GriffeLoader.resolve_module_aliases]
+- All parameters of the [`resolve_aliases`][griffe.GriffeLoader.resolve_aliases] method are now keyword-only.
+- Parameters `only_exported` and `only_known_modules` of the [`resolve_module_aliases`][griffe.GriffeLoader.resolve_module_aliases]
     method were removed. This method is most probably not used by anyone, and will probably be made private in the future.
 
 ### Deprecations
 
-- Parameters `only_exported` and `only_known_modules` of the [`resolve_aliases`][griffe.loader.GriffeLoader.resolve_aliases]
+- Parameters `only_exported` and `only_known_modules` of the [`resolve_aliases`][griffe.GriffeLoader.resolve_aliases]
     method are deprecated in favor of their inverted counter-part `implicit` and `external` parameters.
 
     - Example before: `loader.resolve_aliases(only_exported=True, only_known_modules=True)`

CONTRIBUTING.md

@@ -1,151 +1,13 @@
 # Contributing
 
-Contributions are welcome, and they are greatly appreciated!
-Every little bit helps, and credit will always be given.
+Thank you for considering contributing to this project!
 
-## Environment setup
+We provide a guide for contributors. If you are reading this locally or directly on GitHub, check the following documents:
 
-Nothing easier!
+- Contributors guide: [docs/guide/contributors.md](docs/guide/contributors.md)
+    - Environment setup: [docs/guide/contributors/setup.md](docs/guide/contributors/setup.md)
+    - Management commands: [docs/guide/contributors/commands.md](docs/guide/contributors/commands.md)
+    - Development workflow: [docs/guide/contributors/workflow.md](docs/guide/contributors/workflow.md)
+    - Project architecture: [docs/guide/contributors/architecture.md](docs/guide/contributors/architecture.md)
 
-Fork and clone the repository, then:
-
-```bash
-cd griffe
-make setup
-```
-
-> NOTE:
-> If it fails for some reason,
-> you'll need to install
-> [uv](https://github.com/astral-sh/uv)
-> manually.
->
-> You can install it with:
->
-> ```bash
-> python3 -m pip install --user pipx
-> pipx install uv
-> ```
->
-> Now you can try running `make setup` again,
-> or simply `uv install`.
-
-You now have the dependencies installed.
-
-You can run the application with `make run griffe [ARGS...]`.
-
-Run `make help` to see all the available actions!
-
-## Tasks
-
-The entry-point to run commands and tasks is the `make` Python script,
-located in the `scripts` directory. Try running `make` to show the available commands and tasks.
-The *commands* do not need the Python dependencies to be installed,
-while the *tasks* do.
-The cross-platform tasks are written in Python, thanks to [duty](https://github.com/pawamoy/duty).
-
-If you work in VSCode, we provide
-[an action to configure VSCode](https://pawamoy.github.io/copier-uv/work/#vscode-setup)
-for the project.
-
-## Development
-
-As usual:
-
-1. create a new branch: `git switch -c feature-or-bugfix-name`
-1. edit the code and/or the documentation
-
-**Before committing:**
-
-1. run `make format` to auto-format the code
-1. run `make check` to check everything (fix any warning)
-1. run `make test` to run the tests (fix any issue)
-1. if you updated the documentation or the project dependencies:
-    1. run `make docs`
-    1. go to http://localhost:8000 and check that everything looks good
-1. follow our [commit message convention](#commit-message-convention)
-
-If you are unsure about how to fix or ignore a warning,
-just let the continuous integration fail,
-and we will help you during review.
-
-Don't bother updating the changelog, we will take care of this.
-
-## Commit message convention
-
-Commit messages must follow our convention based on the
-[Angular style](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message)
-or the [Karma convention](https://karma-runner.github.io/4.0/dev/git-commit-msg.html):
-
-```
-<type>[(scope)]: Subject
-
-[Body]
-```
-
-**Subject and body must be valid Markdown.**
-Subject must have proper casing (uppercase for first letter
-if it makes sense), but no dot at the end, and no punctuation
-in general.
-
-Scope and body are optional. Type can be:
-
-- `build`: About packaging, building wheels, etc.
-- `chore`: About packaging or repo/files management.
-- `ci`: About Continuous Integration.
-- `deps`: Dependencies update.
-- `docs`: About documentation.
-- `feat`: New feature.
-- `fix`: Bug fix.
-- `perf`: About performance.
-- `refactor`: Changes that are not features or bug fixes.
-- `style`: A change in code style/format.
-- `tests`: About tests.
-
-If you write a body, please add trailers at the end
-(for example issues and PR references, or co-authors),
-without relying on GitHub's flavored Markdown:
-
-```
-Body.
-
-Issue #10: https://github.com/namespace/project/issues/10
-Related to PR namespace/other-project#15: https://github.com/namespace/other-project/pull/15
-```
-
-These "trailers" must appear at the end of the body,
-without any blank lines between them. The trailer title
-can contain any character except colons `:`.
-We expect a full URI for each trailer, not just GitHub autolinks
-(for example, full GitHub URLs for commits and issues,
-not the hash or the #issue-number).
-
-We do not enforce a line length on commit messages summary and body,
-but please avoid very long summaries, and very long lines in the body,
-unless they are part of code blocks that must not be wrapped.
-
-## Pull requests guidelines
-
-Link to any related issue in the Pull Request message.
-
-During the review, we recommend using fixups:
-
-```bash
-# SHA is the SHA of the commit you want to fix
-git commit --fixup=SHA
-```
-
-Once all the changes are approved, you can squash your commits:
-
-```bash
-git rebase -i --autosquash main
-```
-
-And force-push:
-
-```bash
-git push -f
-```
-
-If this seems all too complicated, you can push or force-push each new commit,
-and we will squash them ourselves if needed, before merging.
+However we strongly recommend reading the online version at https://mkdocstrings.github.io/griffe/guide/contributors/, as some content is dynamically generated when building the documentation pages.

README.md

@@ -13,6 +13,10 @@ Signatures for entire Python programs. Extract the structure, the frame, the ske
 Griffe, pronounced "grif" (`/ɡʁif/`), is a french word that means "claw",
 but also "signature" in a familiar way. "On reconnaît bien là sa griffe."
 
+- [User guide](https://mkdocstrings.github.io/griffe/guide/users/)
+- [Contributor guide](https://mkdocstrings.github.io/griffe/guide/contributors/)
+- [API reference](https://mkdocstrings.github.io/griffe/reference/api/)
+
 ## Installation
 
 With `pip`:
@@ -46,7 +50,7 @@ $ griffe dump httpx fastapi
 }
 ```
 
-See [the Dumping data section](https://mkdocstrings.github.io/griffe/dumping/) for more examples.
+See the [Serializing chapter](https://mkdocstrings.github.io/griffe/guide/users/serializing/) for more examples.
 
 Or pass a relative path to the `griffe check` command:
 
@@ -68,7 +72,7 @@ Parameter kind was changed:
   New: keyword-only
 ```
 
-See [the API breakage section](https://mkdocstrings.github.io/griffe/checking/) for more examples.
+See the [Checking chapter](https://mkdocstrings.github.io/griffe/guide/users/checking/) for more examples.
 
 **With Python**, loading a package:
 
@@ -90,41 +94,4 @@ for breakage in griffe.find_breaking_changes(previous, current):
     ...
 ```
 
-See [the Loading data section](https://mkdocstrings.github.io/griffe/loading/) for more examples.
-
-## Todo
-
-- Extensions
-    - Post-processing extensions
-    - Third-party libraries we could provide support for:
-        - Django support
-        - Marshmallow support
-        - Pydantic support
-- Docstrings parsers
-    - epydoc
-    - New Markdown-based format? For graceful degradation
-- Serializer:
-    - Flat JSON
-- API diff:
-    - [ ] Mechanism to cache APIs? Should users version them, or store them somewhere (docs)?
-    - [ ] Ability to return warnings (things that are not backward-compatibility-friendly)
-    - List of things to consider for warnings
-        - Multiple positional-or-keyword parameters
-        - Public imports in public modules
-        - Private things made public through imports/assignments
-        - Too many public things? Generally annoying. Configuration?
-    - [x] Ability to compare two APIs to return breaking changes
-    - List of things to consider for breaking changes
-        - [x] Changed position of positional only parameter
-        - [x] Changed position of positional or keyword parameter
-        - [ ] Changed type of parameter
-        - [ ] Changed type of public module attribute
-        - [ ] Changed return type of a public function/method
-        - [x] Added parameter without a default value
-        - [x] Removed keyword-only parameter without a default value, without **kwargs to swallow it
-        - [x] Removed positional-only parameter without a default value, without *args to swallow it
-        - [x] Removed positional-or_keyword argument without a default value, without *args and **kwargs to swallow it
-        - [x] Removed public module/class/function/method/attribute
-        - [ ] All of the previous even when parent is private (could be publicly imported or assigned somewhere),
-            and later be smarter: public assign/import makes private things public!
-        - [ ] Inheritance: removed, added or changed base that changes MRO
+See the [Loading chapter](https://mkdocstrings.github.io/griffe/loading/) for more examples.