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

Documentation overhaul #1677

Merged
merged 5 commits into from May 30, 2022
Merged

Documentation overhaul #1677

merged 5 commits into from May 30, 2022

Conversation

jensens
Copy link
Contributor

@jensens jensens commented May 30, 2022

@jensens jensens added enhancement This issue/PR relates to a feature request. documentation This issue/PR relates to or includes documentation. labels May 30, 2022
@jensens jensens marked this pull request as ready for review May 30, 2022
@jensens jensens requested review from insspb, ssbarnea and ericof May 30, 2022
@codeclimate
Copy link

codeclimate bot commented May 30, 2022

Code Climate has analyzed commit f011240 and detected 0 issues on this pull request.

The test coverage on the diff in this pull request is 100.0% (0% is the threshold).

This pull request will bring the total coverage in the repository to 100.0% (0.0% change).

View more on Code Climate.

ericof
ericof approved these changes May 30, 2022
Copy link
Member

@ericof ericof left a comment

LGTM

@ericof ericof merged commit e994273 into master May 30, 2022
19 checks passed
@ericof ericof deleted the doc-overhaul branch May 30, 2022
@insspb
Copy link
Member

insspb commented Jun 6, 2022

@jensens thank you for contribution, but please do not do this in future:

doc style: one line per sentence (not everywhere yet). Hint: in case anyone wants to translate the docs in future.

Documentation translate make any project less maintainable (if it is not something with huge use), but such changes makes documentation in files harder to read.

@ericof Please consider my note in future documentation merges.

@jensens
Copy link
Contributor Author

jensens commented Jun 7, 2022

Documentation is not code, we did large documentations in the past with real experts on the topic.
One sentence per line is the standard.
So we should stick to it.

If you use Sphinx and may want to translate the docs in future (which may happen), then there is no way around this rule.
It is a question about inclusiveness, not about readability.

Nice side effects: Better readability on git diff after changes, easier to write (no manual newlines after inserting/removing words in a sentence and so on.

@insspb
Copy link
Member

insspb commented Jun 7, 2022

@jensens i do not remember any translation attempts. We do not have complete documentation in english. Nothing to say about other languages. But I remember moving to markdown #1216, and this will be done in future for most not auto-generated modules, as Myst support for rst is very elegant too.

About docs not a code. Docs for end users is much more required, but to develop a doc you need to look inside.
But did you tried to read 231 characters string on small screen? try, it will be fun.

Check pre-commit file history to find out how rst checks was set up in past. (2020) also check history of setup.cfg.

As for side effects etc... I cannot agree with it.

As is standart, For subtitles and things like that for sure. For docs? I see it first time. I do not know any maintainer, who want to watch and work with doc translation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation This issue/PR relates to or includes documentation. enhancement This issue/PR relates to a feature request.
Projects
None yet
3 participants