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

Improve docs #503

Merged
merged 28 commits into from
Nov 7, 2023
Merged

Improve docs #503

merged 28 commits into from
Nov 7, 2023

Conversation

James-Mart
Copy link
Member

@James-Mart James-Mart commented Oct 30, 2023

Content changes

  • I deleted the docs that describe how to generate wildcard certs with certbot, and use nginx/godaddy. Those instructions were too specific and could become outdated if those third-parties change and therefore they are outside the scope of our docs. I added a more general replacement in run-infrastructure/configuration/https.md.
  • Rewrote much of the introduction page (/README.md), which was generally outdated and not very well written.
  • Added a brief page describing the intent of the AccountNumbers object (/development/format/account-numbers.md)

Structural changes

  • Eliminated all of the manual tables of contents, and added a table-of-contents plugin that adds TOC to the right hand side of the docs (in desktop view).
  • Reorganized the entire book into categories that I think make more sense. There's a lot more work to be done in this category, but this is a start.
  • Reorganized the structure of the book to have README.md inside each section, which is the convention used by the mdbook docs themselves. Makes it easier to locate the intro page for each section.

Mdbook changes

  • Updated the version of mermaid used by the mdbook-mermaid crate by dynamically loading the mermaid library instead of bundling it with the book. The version bundled with mdbook-mermaid is old.
  • The docs now support the "edit on github" button, which will link to the correct page on which edits are being made.
  • Turned on mdbook-linkcheck by default to detect at build time if anyone breaks links in the docs
  • Turned off the "print" button, which didn't work well for our book anyway with mermaid diagrams, etc.

Further notes

  • Lots of links don't have a corresponding page yet, I don't plan to resolve all missing pages in this PR.

@James-Mart James-Mart marked this pull request as ready for review November 1, 2023 20:16
@James-Mart
Copy link
Member Author

James-Mart commented Nov 2, 2023

Eliminated the doc on app interfaces, which I will add in a separate PR

doc/psidk/src/development/services/README.md Outdated Show resolved Hide resolved
doc/psidk/src/development/services/simpleUI.md Outdated Show resolved Hide resolved
@@ -0,0 +1,13 @@
const script = document.createElement('script');
script.src = 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js';
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know I'm in a minority, but I like being able to view documentation offline...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can, your penalty is just that you will have to deal with a text representation of the mermaid diagram 😜

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The layout has a few issues (depending on the window size)

  • The vertical next button can cover the page TOC making it hard to use it to navigate
  • The size and position of the TOC don't seem to match, as the right side can overflow the window

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • The next/previous buttons have been hidden. Not very useful controls anyways.

  • The TOC is hidden on smaller resolution screens, and the docs look good on at least the following devices with known resolutions:
    image

The only real issue is on desktops where the resolution is unusual or the window is not maximized. I think this won't affect many people and can be fixed later.

doc/psidk/src/applet/applets.md Outdated Show resolved Hide resolved
doc/psidk/src/applet/inter-applet-communication.md Outdated Show resolved Hide resolved
@James-Mart James-Mart merged commit 4810170 into main Nov 7, 2023
3 checks passed
@James-Mart James-Mart deleted the improve-docs branch November 7, 2023 23:44
@James-Mart James-Mart added the Dev Experience Related to the experience of developers label Dec 1, 2023
@James-Mart James-Mart changed the title Improve docs Improve doc-sys app Dec 1, 2023
@James-Mart James-Mart added the documentation Improvements or additions to documentation label Dec 1, 2023
@James-Mart James-Mart changed the title Improve doc-sys app Improve docs Dec 1, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Dev Experience Related to the experience of developers documentation Improvements or additions to documentation
Projects
Status: No status
Development

Successfully merging this pull request may close these issues.

2 participants