-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
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
Automatic mdBook Documentation #2897
Conversation
note that we have also for the internal code: |
maintained here: |
That's a good point, but the purpose is different. This is meant to replace the Sphinx-based documentation. This is meant to be more manual-style and user-focused, whereas the rustdoc documentation is developer-focused. There is also https://docs.rs/uucore/latest/uucore/, which is basically the same as https://uutils.github.io/coreutils-docs/coreutils/. |
docs/src/installation.md
Outdated
@@ -0,0 +1,224 @@ | |||
<!-- spell-checker:ignore UTILNAME DESTDIR --> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this is a bunch of duplication, would it be possible to avoid that?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I didn't think it was possible at first, but I found an mdbook feature to get the instructions directly from the README.md!
By the way, @sylvestre, do you have the original (svg?) files for the uutils logo? I wanted to adapt it for the favicon and put it in the introduction. |
it was before my time. maybe @Arcterus ? |
This is the thread from when it was made. I don't personally have them though, and I can't remember if we ever adjusted it afterwards. |
Thank you! |
docs/src/SUMMARY.md
Outdated
* [Contributing](contributing.md) | ||
|
||
# Reference | ||
* [Multi-call binary](multicall.md) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this list could be generated too, no ? :)
sorry to be a pain but i hate long static list :)
docs/src/index.md
Outdated
|
||
The API reference for `uucore`, the library of functions shared between | ||
various utils, is hosted at at | ||
[docs.rs](https://docs.rs/uucore/0.0.12/uucore/). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[docs.rs](https://docs.rs/uucore/0.0.12/uucore/). | |
[docs.rs](https://docs.rs/uucore/latest/uucore/). |
excellent work, thanks :) |
I love it, well done! Can you add the generation & publication here? |
I did it: updated daily :) |
Following the lead of many Rust projects, I thought it would be nice if we adopted mdBook for the documentation and started generating most of the documentation automatically. The existing documentation was lacking in content, so I removed it (including manpage generation, but we can get that back later via mdBook).
The automatic generation is a bit strange, because we need to extract information from
clap
. So I've added a binary calleduudoc
which uses the same list of utils as thecoreutils
and writes HTML files to adocs/src/utils
directory (which is in.gitignore
). It's far from perfect, but it works surprisingly well already.To generate the docs, you therefore need 2 commands:
I've also written initial versions of an introduction and a page for the multi-call binary. The
CONTRIBUTING.md
file is also included. The layout is based on how The Cargo Book presents their options and flags.To create the initial structure for the book, I used a little python script, which I've included here, so that we can refer to it later, but it isn't strictly necessary anymore.
A temporary hosted version can be found here: https://tertsdiepraam.github.io/uutils-docs/ (until we set it up in the CI)
Edit: Text above is updated to reflect the latest version.