Documentation page: mkdocs & GitHub pages #449

mknorps · 2024-09-03T14:02:09Z

In this PR, a documentation page using mkdocs and deployed on GitHub pages is added.

Documentation content

Documentation page is based on the content available in the current README.md file. The content is split and grouped according to diataxis principles to provide explanations, usage guide and FAQs for FawltyDeps.

To build documentation, mkdocs with mkdocs-material are used due to simplicity and wide support.

Deployment

Documentation page is deployed on GitHub pages (see Settings -> Pages) and is using the content of gh-pages branch.
Content of gh-pages is automatically created with GitHub Action, following the documentation of mkdocs-material.

Local tests

First, install docs dependencies:

poetry install --with docs

Then build and serve locally:

mkdocs build
mkdocs serve

pyproject.toml

Add mkdocs as a documentation framework for FawltyDeps. Update dependencies with a new `docs` dependencies group. Add material-mkdocs.

Create content for the documentation page

Content of README should be shorter. Information suplocated in `docs` is removed.

Add a github action to build and deploy documentation to the GriHub pages.

…itHub rather than internally to the code.

jherland

Big review, lots of comments, but don't be discouraged! I love the look of the docs website, and I'm happy to help in any way I can to get this merged! ❤️

jherland · 2025-01-07T12:14:41Z

docs/explanation.md

+
+To solve this, FawltyDeps uses a sequence of resolvers (aka. mapping strategies)
+to determine which Python packages provide which import names. For more details,
+check [FawltyDeps mapping strategy blogpost](https://www.tweag.io/blog/2023-09-21-fawltydeps-mapping-strategy/). The diagram below


Suggested change

check [FawltyDeps mapping strategy blogpost](https://www.tweag.io/blog/2023-09-21-fawltydeps-mapping-strategy/). The diagram below

check the [FawltyDeps mapping strategy blog post](https://www.tweag.io/blog/2023-09-21-fawltydeps-mapping-strategy/). The diagram below

jherland · 2025-01-07T12:19:57Z

mkdocs.yml

+
+markdown_extensions:
+  - toc:
+      permalink: true


Nit: missing trailing newline

jherland · 2025-01-07T13:29:24Z

docs/CodeDesign.md

 - Support all current Python versions: that means all Python versions that have
-  a stable release, and are not yet End Of Life. Currently this is: v3.7 - v3.11.
+  a stable release, and are not yet End Of Life. Currently this is: v3.8 - v3.13.


Thanks for updating this part. I think it should be updated to reflect that v3.8 is actually EOL, but we still intend to support it for now:

- Support all current Python versions: that means [all Python versions that have a stable release, and are not yet End Of Life](https://devguide.python.org/versions/). - We also try to support older (EOL-ed) Python versions, when doing so is not too expensive. - Currently we support running on Python v3.8 - v3.13. - Since we no longer rely on running inside the same Python environment as the project being analyzed, it is possible for us to support analyzing projects running on even older Python versions.

More generally, this file is starting to show its age (e.g. the sentence about Windows below), and would benefit from another pass to make it more up-to-date (not in this PR! 😅).

jherland · 2025-01-07T13:34:48Z

docs/images/fd_dependencies.png

The transparent background on this picture (and the next) does not display well in dark mode:

jherland · 2025-01-07T14:30:51Z

docs/index.md

+# FawltyDeps
+
+FawltyDeps is an open-source Python tool that checks your dependencies to ensure they are being used correctly. It helps you identify any dependencies listed in your `requirements.txt` or `pyproject.toml` that are not actually used in your codebase, and vice versa.
+
+![FawltyDeps demo](images/fawltydeps_demo_tqdm.gif)
+
+## Features
+
+- Detect unused dependencies
+- Identify missing dependencies
+- Supports multiple project structures
+
+## Why FawltyDeps?
+
+Dependency management is crucial for maintaining a healthy codebase. Over time, unused dependencies can accumulate, leading to bloated environments, longer installation times, and potential security risks. FawltyDeps helps keep your project clean and efficient.
+
+
+We [invite you](https://discord.gg/V2d9xpgD4D) to join our [Discord channel](https://discord.com/channels/1174731094726295632/1176462512212951090)! It's a great place to ask questions, share your ideas, and collaborate with other contributors.


Love this new and simpler frontpage! 😻 But I think the intro sentence in the old README reads better, and can be reused here. Also adding some more suggestions here:

Suggested change

# FawltyDeps

FawltyDeps is an open-source Python tool that checks your dependencies to ensure they are being used correctly. It helps you identify any dependencies listed in your `requirements.txt` or `pyproject.toml` that are not actually used in your codebase, and vice versa.

![FawltyDeps demo](images/fawltydeps_demo_tqdm.gif)

## Features

- Detect unused dependencies

- Identify missing dependencies

- Supports multiple project structures

## Why FawltyDeps?

Dependency management is crucial for maintaining a healthy codebase. Over time, unused dependencies can accumulate, leading to bloated environments, longer installation times, and potential security risks. FawltyDeps helps keep your project clean and efficient.

We [invite you](https://discord.gg/V2d9xpgD4D) to join our [Discord channel](https://discord.com/channels/1174731094726295632/1176462512212951090)! It's a great place to ask questions, share your ideas, and collaborate with other contributors.

# FawltyDeps

FawltyDeps is a dependency checker for Python that finds _undeclared_ and/or _unused_ 3rd-party

dependencies in your Python project. For example, it will find modules that you are `import`ing in

your code, but have forgotten to declare in your `pyproject.toml` or `requirements.txt`.

![FawltyDeps demo](images/fawltydeps_demo_tqdm.gif)

## Features

- Finds undeclared dependencies: modules you are `import`ing, but forgot to declare as dependencies.

- Finds unused dependencies: dependencies you declared, but never `import`.

- Supports Python code in regular files and Jupyter notebooks.

- Supports many dependency declaration formats: `pyproject.toml`, `requirements.txt`, `setup.py`,

`setup.cfg`, `environment.yml`, and `pixi.toml`.

- Can be installed into your project as a development dependency, or run as an independent tool.

- Easily automated, e.g. as a pre-commit hook or as a CI action.

## Why FawltyDeps?

Good dependency management is crucial for maintaining a healthy codebase and avoiding the

"Works on my machine" problem. Over time, unused dependencies can accumulate, leading to

bloated environments, longer installation times, and potential security risks. FawltyDeps helps

keep your project installable, lean and efficient.

We [invite you](https://discord.gg/V2d9xpgD4D) to join our [Discord channel](https://discord.com/channels/1174731094726295632/1176462512212951090)!

It's a great place to ask questions, share your ideas, and collaborate with other users and contributors.

The name "FawltyDeps" is inspired by the Monty Python-adjacent Fawlty Towers sitcom.

jherland · 2025-01-07T19:56:14Z

.github/workflows/docs.yaml

+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force


Nit: missing trailing newline

jherland · 2025-01-07T19:57:22Z

.github/workflows/docs.yaml

+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com


This looks very hard-coded. Where is this identity coming from?

jherland · 2025-01-07T20:06:14Z

.github/workflows/docs.yaml

+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-


Not sure what's going on here, the date --utc '+%V' prints the current week number, IIUC. Why is this appropriate as a cache key?

jherland · 2025-01-07T20:09:29Z

.gitignore

+# Documentation
+site/


This is the default location used by mkdocs, I assume? I don't see site/ referenced anywhere else in these changes...

jherland · 2025-01-07T20:11:55Z

.github/workflows/docs.yaml

+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force


Ideally, this should used the docs dependency group that you added to pyproject.toml? And even more ideally (and I can easily do this in a separate PR), we should wrap this is a Nox action, so that we can easily generate the docs locally too?

mknorps self-assigned this Sep 3, 2024

mknorps added the type: documentation label Sep 3, 2024

mknorps added this to the FawltyDeps 1.0 milestone Sep 3, 2024

jherland reviewed Sep 16, 2024

View reviewed changes

pyproject.toml Show resolved Hide resolved

mknorps force-pushed the mknorps/documentation-init branch 7 times, most recently from 82f046d to 4932a58 Compare December 27, 2024 12:54

mknorps temporarily deployed to github-pages December 30, 2024 12:19 — with GitHub Pages Inactive

Add mkdocs configuration

ae88479

Add mkdocs as a documentation framework for FawltyDeps. Update dependencies with a new `docs` dependencies group. Add material-mkdocs.

mknorps force-pushed the mknorps/documentation-init branch 2 times, most recently from 6c410db to ce7a0ab Compare December 30, 2024 14:32

mknorps temporarily deployed to github-pages December 30, 2024 14:32 — with GitHub Pages Inactive

mknorps force-pushed the mknorps/documentation-init branch 2 times, most recently from b7f16d5 to dfb1799 Compare December 30, 2024 15:00

Create documenation pages

3df7609

Create content for the documentation page

mknorps force-pushed the mknorps/documentation-init branch 4 times, most recently from 5870a05 to d218819 Compare December 31, 2024 14:43

Adjust content of the README

b87956a

Content of README should be shorter. Information suplocated in `docs` is removed.

mknorps force-pushed the mknorps/documentation-init branch from d218819 to a7e8e0e Compare December 31, 2024 14:47

mknorps marked this pull request as ready for review December 31, 2024 14:48

mknorps requested a review from jherland December 31, 2024 14:48

mknorps changed the title ~~WIP: MkDocs documentation page~~ MkDocs documentation page Dec 31, 2024

mknorps linked an issue Dec 31, 2024 that may be closed by this pull request

Create a documentation page according to diataxis principle #231

Open

mknorps changed the title ~~MkDocs documentation page~~ Documentation page: mkdocs & GitHub pages Dec 31, 2024

mknorps added 2 commits December 31, 2024 15:58

GitHub workflow to publish documentation

e43e9e3

Add a github action to build and deploy documentation to the GriHub pages.

Change links in COTRIBUTING.md to point to FawltyDeps repository on G…

a23d59c

…itHub rather than internally to the code.

mknorps force-pushed the mknorps/documentation-init branch from a7e8e0e to a23d59c Compare December 31, 2024 14:58

mknorps requested review from zz1874, Nour-Mws and obscurerichard January 2, 2025 07:01

jherland requested changes Jan 7, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation page: mkdocs & GitHub pages #449

Documentation page: mkdocs & GitHub pages #449

mknorps commented Sep 3, 2024 •

edited

Loading

jherland left a comment

jherland Jan 7, 2025

jherland Jan 7, 2025

jherland Jan 7, 2025

jherland Jan 7, 2025

jherland Jan 7, 2025

jherland Jan 7, 2025

jherland Jan 7, 2025

jherland Jan 7, 2025

jherland Jan 7, 2025

jherland Jan 7, 2025

	check [FawltyDeps mapping strategy blogpost](https://www.tweag.io/blog/2023-09-21-fawltydeps-mapping-strategy/). The diagram below
	check the [FawltyDeps mapping strategy blog post](https://www.tweag.io/blog/2023-09-21-fawltydeps-mapping-strategy/). The diagram below

		git config user.name github-actions[bot]
		git config user.email 41898282+github-actions[bot]@users.noreply.github.com

		- run: pip install mkdocs-material
		- run: mkdocs gh-deploy --force

		# Documentation
		site/

Documentation page: mkdocs & GitHub pages #449

Are you sure you want to change the base?

Documentation page: mkdocs & GitHub pages #449

Conversation

mknorps commented Sep 3, 2024 • edited Loading

Documentation content

Deployment

Local tests

jherland left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mknorps commented Sep 3, 2024 •

edited

Loading