Fix docs typo - Githubissues

m3dev / gokart

Gokart solves reproducibility, task dependencies, constraints of good code, and ease of use for Machine Learning Pipeline.

https://gokart.readthedocs.io/en/latest/

MIT License

318 stars 57 forks source link

Fix docs typo #200

Closed mski-iksm closed 3 years ago

mski-iksm commented 3 years ago

I've fixed a small typo and added section number to make document easy to read.

Please review! @Hi-king @hirosassa @vaaaaanquish

vaaaaanquish commented 3 years ago

By not following the formatting and numbering, tree is not shown.

Use the following command

sphinx-autobuild docs/ build

vaaaaanquish commented 3 years ago

I don't know why it need a numbering. Each item is independent. Excessive numbering can mislead users.

mski-iksm commented 3 years ago

By not following the formatting and numbering, tree is not shown.

Use the following command
sphinx-autobuild docs/ build

@vaaaaanquish Do you mean that subcategories (i.e. 1. gokart.TaskInstanceParameter) are not shown in this list? I think thats how this listing works, since other subsections are not shown too.

mski-iksm commented 3 years ago

I don't know why it need a numbering. Each item is independent. Excessive numbering can mislead users.

@vaaaaanquish I thought the difference between section and subsection is hard to distinguish which makes hard to read.

But as mentioned, numbering can mislead users that they have follow the orders, so I though A, B, C... may be better. How do you think of it?

vaaaaanquish commented 3 years ago

@mski-iksm

I thought the difference between section and subsection is hard to distinguish which makes hard to read.

This is important misunderstanding. It's not a "writing section problem", but a "sphinx design problem".

It's same you saying following

is bad
```
# Title
---
```

foo

This is foo section

bar

barA
barB

is good
```
# Title
---
```

1, foo

This is foo section

2, bar

barA
barB
```
---
```

If you have written Markdown, you know that the former is good. And this PR is the latter.

Can you explain why TaskInstanceParameter is 1 and ListTaskInstanceParameter is 2? If you can't do it, then it's a mistake to make it numbering.

vaaaaanquish commented 3 years ago

numbering

If you have examples in other OSS, please share them:)

mski-iksm commented 3 years ago

@vaaaaanquish I've separated the descriptions of Setting Task Parameters to a new file setting_task_parameters.rst.

vaaaaanquish commented 3 years ago

LGTM. Thanks good PR.

hirosassa commented 3 years ago

@mski-iksm Thank you for your improvement!