Addons: Link API docs with with tensorflow.org

[seanpmorgan]

Given the discussion in this comment: https://github.com/tensorflow/addons/pull/140#discussion_r276059512

And the API docs generated for release 0.3:
https://github.com/tensorflow/addons/tree/r0.3/docs/api_docs/python

I believe we're almost ready to link our docs with the tensorflow.org website? Looks like we need some landing page files and a few configs?

Is there information somewhere about what all needs to be done? @lamberta @Markdaoust

[lamberta]

Hi Sean,
Glad the API gen is working! I have a WIP internal config that will import the API docs to publish on tensorflow.org, but we still need to figure out how to surface it. Probably under https://www.tensorflow.org/api_docs/python/tf/addons but unclear how the versoning will work. The root docs reflect stable (currently r1.13) but TFA (0.3) isn't tied to this.
Eventually we want to surface all the reference APIs in one place so we'll need to figure this out ... but probably will have to wait until after Google I/O next week.

These files are all you need, for now. We don't have plans to create a tensorflow.org/addons site, but if you get some docs/notebooks together, we can link here from https://www.tensorflow.org/resources/libraries-extensions

edit: Sorry, we can link to the repo from /resources/libraries-extensions regardless, but you can always create a top-level /docs directory that would match the other projects.

[seanpmorgan]

Thanks for the clarification Billy! I agree the APIs might want to wait for TF2 seeing as we're not compatible with the current TF release.

We'll look to add some narative docs on our master branch to make the directory more friendly, but in the mean time could we add Addons to that extensions page? Or should that wait for TF2 release as well?

[lamberta]

SG. I filed b/131839445 to add TF Addons to the Resources page.

[shashvatshahi1998]

@seanpmorgan can I contribute in it ?

[seanpmorgan]

Hi @lamberta with 2.0 RC0 being out we were wondering what the status of this issue is?

https://github.com/tensorflow/addons/tree/r0.5/docs/api_docs/python is pinned to the release candidate, but will linking to tensorflow.org need to wait for the full release?

Also gentle ping on b/131839445

[MarkDaoust]

@adammichaelwood,

While you're looking at tensorflow/agents can you look at tensorflow/addons? It's exactly the same process.

Two quick questions for stake-holders:

1. Is there any reason not to make this a real project-subsite? tensorflow.org/addons?

2. Is there any reason not to use the examples directory as a tutorials/ tab? These look really well done.

[seanpmorgan]

@adammichaelwood,

While you're looking at tensorflow/agents can you look at tensorflow/addons? It's exactly the same process.

Two quick questions for stake-holders:

1. Is there any reason not to make this a real project-subsite? tensorflow.org/addons?
2. Is there any reason not to use the examples directory as a tutorials/ tab? These look really well done.

1. No reason I can think of.. that'd be much appreciated!
2. Sounds great. That'll allow us to easily build out more tutorials on the site.

[facaiy]

Sounds great. That'll allow us to easily build out more tutorials on the site.

Yes, great suggestion, we weren't aware of that

[facaiy]

@MarkDaoust Hi, would you mind introducing how to integrate tutorials with API pages on tensorflow.org? I mean, what need we to do? Create a markdown index file for the example directory manually? Thanks

[MarkDaoust]

There is this template directory we use as a starting point:

https://github.com/tensorflow/docs/tree/master/tools/templates/subsite

The main idea is to have directory for the docs, including a landing page (_index.yaml), some metadata (_project.yaml) and the nav description (_book.yaml).

We support notebooks and markdown.

You don't need to have the api_docs checked into github (which was the plan earlier). We can generate them from the pip package when we build the site.

The docs directory doesn't need to be called g3doc, you can call it whatever you want.

We can help you get setup, but you will need to maintain it.

Ideally the tensorflow/docs team would have commit access for the docs directory, so that we can make global changes when necessary.

[seanpmorgan]

@MarkDaoust @lamberta Since #486 and #518 have been merged just wondering if there is anything else you needed from us?

Re-opening this for tracking until this is finalized.

[MarkDaoust]

Okay, we worked out some internal issues that were blocking us.

I think everything is working now, in #566 I hide the template.ipynb because it's not actually a runnable/publishable notebook. Anything prefixed with an underscore is ignored by our publisher.

[lamberta]

Rather than forking the notebook template, can we add a readme that links off to the tensorflow/docs template: https://github.com/tensorflow/docs/blob/master/tools/templates/notebook.ipynb ?
Can include the tfa imports in the readme. And this way we can keep the other template up-to-date.
(Now that you have some notebooks in here, the template might be less important anyway.)

[MarkDaoust]

Okay, I've got addons up on our staging site (screenshot).

I'll send it out for reviews on Monday.

I think we will take the _book and _project file out of your repo since there's no good way for you to debug them.

[MarkDaoust]

Up: https://www.tensorflow.org/addons

[MarkDaoust]

Let us know if anything looks out of place, or when you release a new version and we'll update the site.

[seanpmorgan]

Thanks @MarkDaoust looks great! Is there an ETA for the API docs to go up (or maybe I'm just missing them)?

EDIT -----
Whoops... found them:
https://www.tensorflow.org/addons/api_docs/python/tfa

[seanpmorgan]

@MarkDaoust would it be possible to link Addons under Resources in TF API overview or is that reserved space?

[lamberta]

We're working on a plan to revamp that entire section. Still some things to work out for libraries and extensions—like version compatibility, etc.

But, in the meantime, I can look at adding a list similiar to what's now at the bottom of the /tutorials and /guide page.

[MarkDaoust]

The above commit updates the left-nav on https://tensorflow.org/api_docs to include addons and other recent additions.