documentation

[fafhrd91]

No description provided.

[messense]

I think we could upload cargo doc generated documentation to gh-pages branch in Travis CI master branch build.

Or if we publish this crate to crates.io then we can simply use docs.rs: https://docs.rs/pyo3

[fafhrd91]

We need to write new documentation. Publishing is not a problem

[messense]

Yeah, after pyptr landed, it's getting a little confusing when to use PyObject, when to use Py<'p, PyObject>', when to use PyPtr<PyObjectMarker> and when to use pptr<'p>.

Some documentation to clarify them would be great. Also the examples in README.md may need to be updated.

[fafhrd91]

@messense could you help me with documentation?

[messense]

Sure. So what do we want for documentation? I think we need to write a user guide and add more docs to APIs. For guide we need to make a outline.

[fafhrd91]

user guide and more docs for apis, sounds good

[messense]

I think mdBook could be a great choice to write user guide. I'll try it.

[messense]

I'd like to divide the user guide to the following chapters:

1. Overview: Very much like current README.md
2. Getting Started: A tutorial to create a simple project including implementing classes, methods, functions and hopefully object protocols as well as some error handling code.
3. Conversions: Explain how Python types and Rust types are converted to each other.
4. Exception: how to define and use Python exceptions in Rust code and how to transform Rust erros to Python exceptions.
5. Module: how to init a module and add setuptools support
6. Function: how to write and register functions, inevitably talk about argument parsing, positional args, keyword args, *args, **kwargs, *.
7. Class: how to write and register classes, how to implement object protocols on them.
8. Maybe more about object protocols, like async, await support
9. True parallelism: How to take advantage of threads by releasing GIL, use rayon to do some CPU intensive work for example.
10. Distribution: Talk about sdist, bdist_wheel, manylinux

What do you think?

[fafhrd91]

very good plan. I like it.

[messense]

I'd like to make sure user guide examples actually compile, waiting for https://github.com/azerupi/mdBook/pull/340 to land.

[fafhrd91]

sure

[fafhrd91]

@messense if you have any docs, let's just commit. mdbook fix does not matter at the moment

[messense]

Didn't write any more docs when #41 was ongoing. I'll need to read through #42 then get back to this.

[messense]

Do we really need to reexport Py_hash_t and Py_ssize_t? They should be accessible through ffi::Py_hash_t and ffi::Py_ssize_t.

Should we hide argparse module from API documentation? It seems not to be directly used by end user.

[fafhrd91]

Good point on both. I agree

[radhikasundararaman24]

Hello: Are you looking for some documentation help? I'm a programming technical writer and would be interested to know more about your documentation needs.

[konstin]

Closing in favor of #306