Addons: Generate API docs

[seanpmorgan]

As our repository matures it's important to have api docs to improve user experience. As discussed in #38 we will also be able to remove the table of contents off the main README.

Should we host on https://readthedocs.org/ or is there something else recommended @ewilderj @dynamicwebpaige @karmel ?

[armando-fandango]

• TensorFlow API docs are here: https://www.tensorflow.org/api_docs
• Go TensorFlow API docs are here: https://godoc.org/github.com/tensorflow/tensorflow/tensorflow/go
• Haskell TensorFlow docs are here: https://github.com/tensorflow/haskell and here https://tensorflow.github.io/haskell/haddock/
• There are 4 more different links for community supported docs for Julia, Ruby, Rust, Scala

Would it be possible to host the docs in tensorflow.org in someway, so that a reader can seamlessly flow between Core TensorFlow docs and Addons docs ?

[facaiy]

Agree with @armando-fandango, I prefer to host it on tensorflow.org as well.

cc @martinwicke

[karmel]

@markdaoust and @lamberta - is this feasible? Having these in the community docs on TF.org would be nice.

[ewilderj]

Yes, it would be desirable to figure out a way to do this on the main site, as there are ever more satellite repos // cc Billy @lamberta

[lamberta]

@markdaoust knows more about API doc gen, but our doc gen tools are here: https://github.com/tensorflow/docs/tree/master/tools/tensorflow_docs

As far as publishing guides and tutorials on tensorflow.org, yes, this is possible from a technical standpoint and we're already set up for it :)
We use "subsites" for some projects not in TensorFlow core, for example, here's the subsite directory for TensorFlow Probability. Here's the subsite template.

But there are organization issues to figure out for how we present these. We'll probably need to label them as "non-official". And if anything is hosted on tensorflow.org then the review requirements increase since we open ourselves to potential abuse, etc. But it's worth exploring and I think it would be helpful.

[MarkDaoust]

For api_docs this is simplest if these projects generate api docs into their docs/ directory here on github.

And we can pull the docs/ into the site.

The best example of how to use the doc generator is here:

https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/docs/generate2.py#L88+

For most packages the script can be simplified somewhat (delete most flags, delete TfExportAwareDocGeneratorVisitor).

To install the docs-generator, there's no pip package. just use:

pip install git+https://github.com/tensorflow/docs

[armando-fandango]

Summary of above discussion:

• In principle it would be a better user-experience to keep the docs in a way that it is easier for engineer/reader/user to navigate between core TensorFlow and 'satellite site' docs easily.
• Label the docs not part of core as "Contributed" or "Community Docs"
• Generate the docs in /docs folder, example: https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/docs/generate2.py#L88+
• TensorFlow core team will then figure out a way to reduce risk with extra messages like "Community Docs" etc., and pull them into the TensorFlow.org where other docs reside.

If we agree on this, then let us create an issue to generate docs as per the example.

[karmel]

That matches my understanding; @lamberta / @MarkDaoust can you confirm?

Thanks, Addons team, for making sure this is done thoroughly and correctly for the users.

[lamberta]

👍 The more I think about it the more I like it, especially as a blueprint for other SIGs :)

Feel free to post to this the docs list and maybe we can get some more input.

[dynamicwebpaige]

We'll also want to make sure to include this as part of the TensorFlow Contributor Guide. Thank you for formalizing this process and for creating standards! We appreciate it. :slightly_smiling_face: