orium / cargo-rdme

Cargo command to create the README.md from your crate's documentation
Mozilla Public License 2.0
126 stars 5 forks source link

Feature Request: unwrapped paragraphs #160

Open Lucretiel opened 1 year ago

Lucretiel commented 1 year ago

It should be possible for cargo-rdme to output prose paragraphs that are not wrapped into multiple lines, but instead are on a single line. Some projects prefer this style because of, among other reasons, the friendliness towards git diffs.

orium commented 1 year ago

I think a useful generalization of this feature is to allow the maximum line length to be set. Maybe some people like 80 columns on the README file and some other 120. To have no wrap that configuration would be set to infinity.

pczarn commented 1 year ago

I would like to work on this issue. @orium ?

orium commented 1 year ago

Sounds good. Take a look at the Markdown structure and add a function like fn with_line_width(&self, line_width: Option<usize>) -> Markdown.

Make sure it doesn't break markdown incorrectly. Use pulldown-cmark, which is already a dependency to parse and process the markdown. Add a decent amount of unit tests.

It should also add both a command line flag (--line-width) and configuration file setting (line-width). Add integration tests for both please.

Also, it shouldn't just make lines shorter. They can also be made longer if the original rustdoc was not using all the width we want in the README.md.

pczarn commented 1 year ago

Ok.

pczarn commented 1 year ago

@orium Should I wrap list items as well? Example:

* This is another item.
    * This is yet another
next level item. The purpose
of this level is to check
for correct identation within
lists.
* Item.
*  Item with some whitespace.
*   Item with more whitespace.
orium commented 1 year ago

Yes. Ideally what can be nicely wrapped should be wrapped. (For instance, for tables I don't think there is a way to wrap them, but even if there was we probably shouldn't.)

pczarn commented 1 year ago

Should I indent wrapped lines in lists, or leave them unindented like above?

Indentation for lists is harder to implement.

orium commented 1 year ago

Leave them unindented.