I migrated the documentation in this repository from GitBook to mdBook as a trial, and the documentation generated using mdBook can be viewed here. The content has not been changed except for the notations. Your feedback would be appreciated.
The motivation for the migration is to make it easier for everyone to generate HTML documents in his/her local environment using a standard document generation system in the Rust world.
How to generate HTML files
% mdbook build
HTML files are generated in the book directory.
Remarks
Rust Playground integrations
With mdBook, code can be executed "directly" within the book instead of in the Playground in a separate window. Users cannot modify the code within the book by default. However, if it is preferable to allow users to modify the code within the book as well, we can set it to be editable.
Testing code inside the book
mdBook provides a command called mdbook test, which can be used to check the code in the book. However, this feature currently does not allow us to test code using third-party crates easily, it seems to be better for now to continue with the approach of doing a cargo test within the _skeptic directory to test the code.
Alternative to !FILENAME
Since mdBook does not seem to have a notation for displaying file names at the beginning of code blocks at this time, I have replaced !FILENAME notations with plain Markdown notations.
Theme
For now, I am using the default theme provided by mdBook. Of course, it can be customized.
Automatic generation
In the trial site, HTML files are automatically generated and deployed using GitHub Actions as discussed in #7. I have not included automatic generation in this PR for the time being, as I think it is better to separate the topic.
Closes #17.
I migrated the documentation in this repository from GitBook to mdBook as a trial, and the documentation generated using mdBook can be viewed here. The content has not been changed except for the notations. Your feedback would be appreciated.
The motivation for the migration is to make it easier for everyone to generate HTML documents in his/her local environment using a standard document generation system in the Rust world.
How to generate HTML files
HTML files are generated in the
bookdirectory.Remarks
Rust Playground integrations
With mdBook, code can be executed "directly" within the book instead of in the Playground in a separate window. Users cannot modify the code within the book by default. However, if it is preferable to allow users to modify the code within the book as well, we can set it to be editable.
Testing code inside the book
mdBook provides a command called
mdbook test, which can be used to check the code in the book. However, this feature currently does not allow us to test code using third-party crates easily, it seems to be better for now to continue with the approach of doing acargo testwithin the_skepticdirectory to test the code.Alternative to
!FILENAMESince mdBook does not seem to have a notation for displaying file names at the beginning of code blocks at this time, I have replaced
!FILENAMEnotations with plain Markdown notations.Theme
For now, I am using the default theme provided by mdBook. Of course, it can be customized.
Automatic generation
In the trial site, HTML files are automatically generated and deployed using GitHub Actions as discussed in #7. I have not included automatic generation in this PR for the time being, as I think it is better to separate the topic.