Discussion: use rustdoc for blocks' documentation

[MaxVerevkin]

In-code documentation is just easier to maintain.

The question is whether it is actually convenient for users. Here is an example of documentation (time block): https://maxverevkin.github.io/i3status-rust/doc/i3status_rs/blocks/time/index.html

[ammgws]

I like the idea of increasing maintainability but going with rustdoc it ends up being a bit overwhelming for standard users. Is there a rustdoc option to hide all the struct declarations and such?

[MaxVerevkin]

Unfortunately, I don't think there in an option to hide trait impls (it is possible to hide struct declarations).

I can imagine that if there was an option to output markdown, it would be easy to make the documentation cleaner for users.

From rust-lang/rust#44136 I understand that there were plans to support other output formats but it will never be implemented.

[MaxVerevkin]

Even though per-field documentation is not user-friendly, just writing all block related documentation in the beginning of source code is both convenient to maintain (better than having one huge .md file) and user friendly (is it?):

[ammgws]

Actually that might not be too bad!

[ammgws]

Should we go ahead and do it?

[MaxVerevkin]

@ammgws If you like how https://maxverevkin.github.io/swaystatus/docs/swaystatus/blocks/index.html looks then I suppose.

[ammgws]

It's grown on me

[jyn514]

From rust-lang/rust#44136 I understand that there were plans to support other output formats but it will never be implemented.

That issue was out of date, I updated it - there's an unstable JSON output format on nightly :) rust-lang/rust#76578

[ammgws]

@MaxVerevkin Do the docs have to be checked into the repo like at swaystatus for this to be usable online?

[MaxVerevkin]

I think so, unless we publish the crate on crates.io

[ammgws]

Do others publish programs to crates.io? I always thought it was for libraries that other crates can then import. Wonder if there's another way..

[MaxVerevkin]

Well, there are ripgrep, alacritty and zbus_xmlgen, but... it looks like docs are not generated for binary crates 😞

[jyn514]

docs are not generated for binary crates

rust-lang/docs.rs#238

As a workaround, you could move your current binary to a library with a main function and have the actual binary just call my_lib::main and do nothing else.

[MaxVerevkin]

As a workaround, you could move your current binary to a library with a main function and have the actual binary just call my_lib::main and do nothing else.

Will it work for a crate which is both a library and a binary?

Wonder if there's another way..

Yeah, publishing a new version after every change in documentation doesn't sound great.

[jyn514]

Will it work for a crate which is both a library and a binary?

No, you'd have to make a new library if you want that to work. (or work on the docs.rs issue 😉)

[ammgws]

> @MaxVerevkin Do the docs have to be checked into the repo like at swaystatus for this to be usable online?
I think so, unless we publish the crate on crates.io

Actually if we just keep the docs in a separate branch and have a github action to generate them then we can do this, e.g.: https://github.com/houqp/leptess

[MaxVerevkin]

Actually if we just keep the docs in a separate branch and have a github action to generate them then we can do this, e.g.: https://github.com/houqp/leptess

Nice! Didn't know https://github.com/marketplace/actions/deploy-to-github-pages existed :)

[ammgws]

Closing now that async branch is merged into master. However we now need a way to generate manpages to replace our old script that parsed blocks.md...

[MaxVerevkin]

However we now need a way to generate manpages to replace our old script that parsed blocks.md...

Well... A little script/program can be written to iterate through every file in /src/blocks/ and extract the top-level comment. Those comments can then be concatenated and placed in one big .md file. And then we can convert this file to manpage.

[MaxVerevkin]

My attempt - eb22f91

The result contains some .RS 2 where it doesn't make sense, don't know why yet. fixed in 97d3e0d

[ammgws]

BTW any idea what is going on here? Pretty sure the docs are up to date but code block formatting broken in the Github pages.

[MaxVerevkin]

BTW any idea what is going on here? Pretty sure the docs are up to date but code block formatting broken in the Github pages.

Ahh, that's because markdown is weird and "|" gets parsed as a column separator. Some kind of special escape sequence must be used, like | or something.

[MaxVerevkin]

By the way, perhaps we can remove the "Required" column for better readability (especially in manpages)? Required options are rare and their "Default" can be set to "N/A" or "Required".

[MaxVerevkin]

special escape sequence must be used, like |

And to use this escape sequence you need <code>...</code> instead of `...` 😠

[ammgws]

By the way, perhaps we can remove the "Required" column for better readability (especially in manpages)? Required options are rare and their "Default" can be set to "N/A" or "Required".

Good catch, sounds good to me.

[MaxVerevkin]

TIL that number of - in markdown tables matter (for manpages).

//! Placeholder        | Value
//! -------------------|----------------------------------------------------------------

renders as

while

//! Placeholder        | Value
//! -------------------|------

renders as