[Doc] better documention

[archibate]

Related issue = #736

[Click here for the format server]

[k-ye]

Cool! FYI i think it's better to include native speakers as reviewer.. Again, better to break this down into multiple PRs, otherwise it's hard to do exhaustive reviews

[archibate]

...native speakers as reviewer...

Any native speaker in @taichi-dev? Maybe we can ask @yuanming-hu for help?

[yuanming-hu]

Let me take a pass first.

[yuanming-hu]

One more high-level thing: should we use in-place documentation? @archibate @k-ye
https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions

This will allow us to write documentation together with code.

I think we can have two parts: tutorials and a more complete API reference. Tutorials are written by human and API reference generated automatically.

[archibate]

One more high-level thing: should we use in-place documentation? @archibate @k-ye
https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions

This will allow us to write documentation together with code.

I think we can have two parts: tutoriala and a more complete API reference. Tutorials are written by human and API reference generated automatically.

Sounds like a doxygen will do? But I still want to keep some human-written reference for things like ti.Vector([x, y, ...]), which could be hard if generated by machine(?)

[yuanming-hu]

Sounds like a doxygen will do?

Right, we use sphinx here for the Python part.

But I still want to keep some human-written reference for things like ti.Vector([x, y, ...]), which could be hard if generated by machine(?)

I agree - that's why I believe we should have both tutorials and API references.

[archibate]

Fine, ;et's keep some critical parts to be human-written, like the definition of tensor&vectors. And non-critical parts like the API of GUI, we can machine gen it.

[yuanming-hu]

Thanks for updating the documentation. This is really helpful. I'll take a pass now to fix minor writing issues.

[yuanming-hu]

Before I do my pass, do you mind doing me a favor and fix these Sphinx warnings? No rush on this. Thanks!

/home/yuanming/repos/taichi/docs/atomic.rst:8: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/atomic.rst:15: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/atomic.rst:27: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/atomic.rst:34: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/atomic.rst:41: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/atomic.rst:60: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/atomic.rst:75: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/contributor_guide.rst:80: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/home/yuanming/repos/taichi/docs/contributor_guide.rst:80: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/home/yuanming/repos/taichi/docs/hello.rst:96: WARNING: Title underline too short.

(Sparse) Tensors
-------
/home/yuanming/repos/taichi/docs/hello.rst:96: WARNING: Title underline too short.

(Sparse) Tensors
-------
/home/yuanming/repos/taichi/docs/scalar_tensor.rst:17: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/scalar_tensor.rst:21: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/scalar_tensor.rst:25: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:24: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:42: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:56: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:60: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:76: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:81: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:96: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:109: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:122: WARNING: Unexpected indentation.
/home/yuanming/repos/taichi/docs/vector.rst:138: WARNING: Unexpected indentation.

[archibate]

Before I do my pass, do you mind doing me a favor and fix these Sphinx warnings? No rush on this. Thanks!

No problem! Fixed all WARNINGs except for contributor_guideline.rst, how to fix that? Seems related to the link.

[yuanming-hu]

Thanks! I'm taking a pass. Adding a space after _ seems to fix the remaining warning.

[yuanming-hu]

Looks good in general! I took a pass through atomic, contribution guide, and syntax. I also left a few minor places for you to fix. I'll take a pass through vector and scalar_tensor tomorrow.

A few tips to improve your writing:

• Proofread before posting anything. I usually read carefully what I typed 3-5 times before I click post or submit
• Pay attention to details, such as a, the, punctuation and low-level formats
• Be calm, be positive, and be professional
• Use a spellchecker (I use Grammarly)

[archibate]

Travis can't download openssl? Excuse me?

[yuanming-hu]

Finalized the remaining two files. Thanks for contributing to the documentation!

It's hard to make perfect, but hopefully, readers will catch and fix our errors later.