Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: deploy dedicated docs pages #175

Merged
merged 5 commits into from
Aug 23, 2024
Merged

docs: deploy dedicated docs pages #175

merged 5 commits into from
Aug 23, 2024

Conversation

uniqueg
Copy link
Member

@uniqueg uniqueg commented Aug 23, 2024

Description

Please include a summary of the change and which issue is fixed.
Please also include relevant motivation and context.
List any dependencies that are required for this change.

Fixes #174

Type of change

  • Documentation updated

Conventional Commits guidelines

Checklist:

  • My code changes follow the style of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing tests pass locally with my changes
  • I have updated the project's documentation

@uniqueg
Copy link
Member Author

uniqueg commented Aug 23, 2024

@mkatsanto:

  • I have included a very detailed PR description so that you can see what I did. Note that for the initial build, I did not limit the branches for which docs are built to the dev and main branches. Once the docs.yml GH Action workflow first concluded, the branch gh-pages was available, and I was able to select it from the dropdown list in the GitHub Pages settings in section "Build and deployment". Everything else I left as is.
  • The stuff in bold in the PR description are notes for adding on to the docs in future PRs
  • It's important that you remember to build docs locally to check if everything works as expected when you make changes to the docs (note, however, that some relative links may not always work locally, but I'm not sure) - as docs aren't automatically built and deployed for PRs; it's a bit annoying, but I don't know how to deploy different versions of the docs pages via GitHub Pages (I'm not sure that's even possible), and we don't wanna break the production docs with our unmerged PRs (we would always serve the docs from the last build, from whatever branch, so that's really not good)
  • As for adding beautiful content, MKDocs and especially Material for MKDocs provide super-powered markdown, so there's a lot one can do; for starters, have a look at ZARP-cli docs - they work in exactly the same way, so you can get inspiration from there. But I also recommend you to check the MKDocs and Material for MKDocs docs to see what features are out there - chances are, if you can imagine sth cool, you will most likely find it there
  • Note also that I have left some TODO and NOTE TO SELF markers in the dummy pages (docs/README.md and docs/guides/installation.md) - you will need to address and remove these of course when you add the actual docs in future PRs (also make sure to remove the dummy abbreviation in docs/includes/abbreviations.md - I have just added it so that you can see how it works)
  • Apart from looking at what I did, I don't really think this needs a review, because I have already verified that everything works as expected and so it should be good enough for starters 😝 So once you have looked at everything, approve the PR and merge it

@ninsch3000: I tagged you just FYI. Maybe you have some ideas of stuff that we could put in the docs or how to render it. In that case, feel free to comment here or open issues etc. No need to review the changes.

@uniqueg uniqueg merged commit bc41e3d into dev Aug 23, 2024
11 checks passed
@uniqueg uniqueg deleted the mkdocs branch August 23, 2024 14:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

docs: deploy dedicated docs pages
2 participants