Publish API doc for users

[ki4070ma]

The problem

There are no API doc like below.

• https://www.javadoc.io/doc/io.appium/java-client/7.2.0
• https://www.rubydoc.info/github/appium/ruby_lib/Appium/

(Here is available > http://appium.io/docs/en/about-appium/api/ )

If users can browse API doc easily, it will be helpful.

Candidates

• portray: https://github.com/timothycrosley/portray
• sphinx + napolean extension

TODO

• Create API doc -> https://ki4070ma.github.io/python-client-sphinx/index.html
• Publish API doc
• Improve API doc

[ki4070ma]

Portray

• https://github.com/timothycrosley/portray
• Output
  • https://ki4070ma.github.io/python-client/
• Comments
  • Very easy to generate and publish to github pages
    • $portray on_github_pages -mo appium -f)
  • For now, API doc is unexpected style. (docstring is google style. sphinx is available for its style.)
    • https://ki4070ma.github.io/python-client/reference/appium/webdriver/extensions/keyboard/
    • Here is reference.
      • https://timothycrosley.github.io/portray/reference/portray/api/
        • [Looks good] typing in arguments, description for each argument
        • [No care] Exception, Usage, etc

[ki4070ma]

Asking timothycrosley/portray#47

[ki4070ma]

It's time for trial with sphinx.

[mykola-mokhnach]

I would use our python3 branch for docs generation.

• https://pdoc3.github.io/pdoc/
• https://stackoverflow.com/questions/42283335/can-type-hint-in-python-3-be-used-to-generate-docstring

[ki4070ma]

I'll look into how to change look and feel for each tool.

Samples are here

• https://ki4070ma.github.io/python-client-pdoc/

  • Simple options

• https://ki4070ma.github.io/python-client-sphinx/

  • Many options and extensions

[mykola-mokhnach]

yep, Sphinx with plugins looks much better

[KazuCocoa]

Awesome 🎉 > sphinx

[ki4070ma]

Done https://appium.github.io/python-client-sphinx/