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:

docs/index.md

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

What do you mean? Does the same apply to the previous with key?

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?

The idea is to have a unique GitHub bot identity that does the commits.
We could use something like:

git config user.name "${{ github.actor }}" git config user.email "${{ github.actor }}@users.noreply.github.com"

But that means that the person who merged the PR to the main branch will be markes as the author of the commit for the docs branch.

We could also go a bit simpler, not marking the particular bot, but to say that we use a bot to generate this commit:

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

What do you think would be best?

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?

This whole GitHub action is based on the mkdocs (Publishing your site)[https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions] guide. If you have some other idea for the cache key, we can change the current one.

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?

@jherland

Rewrite front page of the documentation as per @jherland's suggestion Co-authored-by: Johan Herland <[email protected]>

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 Outdated 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

mknorps and others added 2 commits February 3, 2025 18:23

Update docs/index.md

d8ee0a6

Rewrite front page of the documentation as per @jherland's suggestion Co-authored-by: Johan Herland <[email protected]>

Use poetry to install docs dependencies

39db9b2

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

mknorps Feb 3, 2025

jherland Jan 7, 2025

mknorps Feb 3, 2025

jherland Jan 7, 2025

mknorps Feb 3, 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mknorps commented Sep 3, 2024 •

edited

Loading