diff --git a/docs/docs_setup.md b/docs/docs_setup.md index 65457c1..ce0cead 100644 --- a/docs/docs_setup.md +++ b/docs/docs_setup.md @@ -42,9 +42,9 @@ While you *can* manage a static site by locally building and uploading the `site ## Deploy Documentation -Instead of building the docs locally, we will use GitHub Actions to build and deploy the documentation. +We are easily able to deploy documentation to Github Pages where it will be found at `https://.github.io//`. This is a great way to host documentation as a static site, and it is free! On your main repo page, go to the Description settings and check `Use your Github Pages website`. Your documentation, by default, will be served from the `gh-pages` branch. -MkDocs provides a way to manually deploy to GitHub Pages `mkdocs gh-deploy`, but again, this requires local management *and* goes against the ethos of using PRs to manage changes to the codebase. +MkDocs provides a way to locally, manually deploy to `gh-pages` with `mkdocs gh-deploy`, but again, this requires local management *and* goes against the ethos of using PRs to manage changes to the codebase. Instead, we will use a GitHub Action to automatically build the documentation in PRs and commits to main, and deploy the docs to GitHub Pages when a PR is merged to main. MkDocs-Materials provides an action to do this, which is documented in the [MkDocs-Material documentation](https://squidfunk.github.io/mkdocs-material/publishing-your-site/), but we will use a custom action. @@ -89,4 +89,4 @@ While writing this, I got the error in my [action on the PR](https://github.com/ ```bash WARNING - Doc file 'docs-setup.md' contains a link 'docs/gh_repo_settings.md', but the target is not found among documentation files. -``` \ No newline at end of file +``` diff --git a/docs/gh_repo_settings.md b/docs/gh_repo_settings.md index 41210c2..b392919 100644 --- a/docs/gh_repo_settings.md +++ b/docs/gh_repo_settings.md @@ -4,11 +4,9 @@ Use pull requests for all changes to the codebase. Not only does this make changes safer, especially with regards to CI checks, but it also provides a clear history of changes made to the codebase. This is particularly useful for understanding the evolution of the code because it allows you to see what changes were made, when, and by whom. More than just `git blame`, many IDEs provide a way to view the history of the PR, including the discussions and commits that led to the final merged PR. This is invaluable not only for remembering your own work, but for documenting the codebase for others. *Even if you are working on a project alone, using a PR approach will prove invaluable at times.* -A few recommendations to optimize this process: - ## General Repo Settings -Use only Squash and Merge to keep a clean commit history. Use PR title and description to document the merge commit. Again, blame will allow you to find the PR and its discussion. +Use only Squash and Merge to keep a clean commit history. Use PR title and description to document the merge commit. Again, blame will allow you to find the PR and its discussion. ![Github Pull Request Settings](assets/gh-pr-settings.png) @@ -24,7 +22,7 @@ Set up branch protection rules to ensure that the main branch is protected from In Repo Settings -> Rulesets. 1. Name and activate a ruleset -2. Protect the default branch and add the `gh-pages` branch if using for docs. +2. Protect the default branch (`main`). 3. Leave on the default settings 4. Turn on "Require a pull request before merging". Use settings appropriate for yourself or team. 5. Read through the rest of the settings and determine if they are appropriate for your project.