MKDocs integration

[omri374]

MKDocs integration

What are you trying to address

Creating a static website for the playbook based on mkdocs and mkdocs-material.
Demo can be found here: https://omri374.github.io/code-with-engineering-playbook/

To test locally

1. Create a virtual Python env
2. Install the dependencies (pip install -r requirements-docs.txt)
3. Run mkdocs serve

Description of new changes

• Moved content into the docs folder.
• Minor changes to content if necessary for proper rendering on mkdocs.
• Removed relative links to docs in the repo but outside the docs folder (e.g. in the .github folder).
• Added mkdocs.yml which specifies the mkdocs behavior.
• Added a requirements-docs.txt file with the required dependencies for generating the docs.

Still missing

• Align active PRs accordingly (mainly changing the location of files from the root of the repo to the docs folder).
• Reviewing the content to make sure everything is rendered correctly on the mkdocs website.
• Adding Github Action for creating and uploading the website to https://microsoft.github.io/code-with-engineering-playbook.
• Freeze versions on requirements-docs.txt
• Fix linting issues

Relevant issue: #549

For all pull requests

• Link to the issue you are solving (so it gets closed)
• Label the pull request with the appropriate area(s)
• Assign potential reviewers (you may also want to contact them on Teams to ensure timely reviews)
• Assign the project - Engineering Playbook Backlog
• Assign the pull request to yourself

[TessFerrandez]

Looks great!!!

[fnocera]

Looking at the link checking errors these are the ones failing:

FILE: ./CONTRIBUTING.md
[✖] code-reviews/recipes/Markdown.md
[✖] ./code-reviews/pull_request_template.md
[✖] ./source-control/contributing/merge-strategies.md

16 links checked.

ERROR: 3 dead links found!
[✖] code-reviews/recipes/Markdown.md → Status: 400
[✖] ./code-reviews/pull_request_template.md → Status: 400
[✖] ./source-control/contributing/merge-strategies.md → Status: 400

FILE: ./README.md
[✖] ./CSE.md
[✖] ENG-FUNDAMENTALS-CHECKLIST.md
[✖] SPRINT-STRUCTURE.md

21 links checked.

ERROR: 3 dead links found!
[✖] ./CSE.md → Status: 400
[✖] ENG-FUNDAMENTALS-CHECKLIST.md → Status: 400
[✖] SPRINT-STRUCTURE.md → Status: 400

[fnocera]

We can say that the following can come after the first version of this PR is merged in:

• Aligning PRs accordingly
• Consider creating a new domain name for the playbook.

[omri374]

@fnocera I'm working on the linting issues.

[omri374]

@fnocera @TessFerrandez all lint errors are fixed and the GH Action was tested on my fork. PR is ready for review and merge. Demo (https://omri374.github.io/code-with-engineering-playbook/) was re-created last week.

[fnocera]

@brockneedscoffee flagging for your review as well

[fnocera]

Approved - pending review that the new documentation section is merged in/added to the PR.

Thanks so much for this huge contribution @omri374, this will make the playbook look and feel so much more user friendly.

[fnocera]

Approved - pending review that the new documentation section is merged in/added to the PR.

Thanks so much for this huge contribution @omri374, this will make the playbook look and feel so much more user friendly.