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

Move manual to mdbook #13330

Closed
wants to merge 23 commits into from
Closed

Move manual to mdbook #13330

wants to merge 23 commits into from

Conversation

joshrotenberg
Copy link

This PR converts the current single page asciidoc manual into an mdbook project in docs/manual.

Todo list:

  • create a new mdbook project in docs/manual
  • convert static manual adoc to md
  • convert features generated adoc to md
  • convert diagnostics generated adoc to md
  • convert config generated adoc to md
  • convert assists generated adoc to md
  • update xtask/src/release.rs files to point to the .md files
  • split converted manual into separate chapters
  • move docs/dev to new manual (optional, do it later?)
  • update project README.md to include links to the new mdbook site
  • add docs on mdbook and how to update the manual
  • deploy the book (need help here I think)
  • grammar/spelling/typo check
  • markdown lint

Fixes #9504.

(This is a 'take 2' on #10791. I found a much cleaner and consistent way to convert a lot of the adoc with pandoc and it was easier to start fresh with the latest master).

@joshrotenberg
Copy link
Author

Some considerations for the navigation related to automatically generated content ...

Right now, because the four automatically generated sections (Configuration, Assists, Features and Diagnostics) produce a single markdown file for their respective items, their contents are only displayed on the main page using the mdbook toc preprocessor. Note specifically that the navigation does not have the ability to expand down and show the contents) For example:

Screen Shot 2022-10-01 at 12 53 10 PM

While my instinct would be to make them separate, in this case it seems like not cluttering the navigation with excessively long sub item lists is preferable, and just having them exist on a single page makes it easier to CtrlF through (as I believe is pointed out as a desirable feature in #9504).

Adding to the searchability, the mdbook built-in search gives good results when searching for, say, a specific assist:

Screen Shot 2022-10-01 at 1 04 00 PM

More screenshots with other themes ...

Installation
Screen Shot 2022-10-01 at 12 47 57 PM

Contributing guide (previously the content in docs/dev)

Screen Shot 2022-10-01 at 1 05 02 PM

@Veykril Veykril added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Nov 3, 2022
@joshrotenberg joshrotenberg closed this by deleting the head repository Jun 25, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Manual needs to be more helpful, friendly, and better organized
2 participants