Initial setup for tensorflow subsite

[seanpmorgan]

Starting a PR to close #226

[seanpmorgan]

It's difficult to check that these links are working correctly... Is it possible for the Docs team to test this PR or show us how to do that as a webpage?

Also, I didn't immediately see why overview.md and bar_guide.md are part of the template directory. Are these required?

[seanpmorgan]

Granted the docs team write permission as well.

[seanpmorgan]

@lamberta @MarkDaoust changes made, thanks! What would be the path forward for testing this?

[lamberta]

Great, thanks.
As far as testing notebooks, @yashk2810 has some CI set up in the tensorflow/docs repo. Not sure of the plan to extend that to other repos, but would be cool.
As far as full staging and previews, I don't think that's possible with our internal site infra. But if it works in the GitHub Markdown previewer and in Colab, then it should render fine on tensorflow.org. But if there's a launch or something, you can ping me (or someone) to stage internally and double check things.

[seanpmorgan]

@lamberta So this part I'm still unclear on. Where does the directory "addons" come from? Is it just the repository name?

Does it need to be addons/docs/tutorials/*?

[MarkDaoust]

"/addons/tutorials/losses_triplet" is correct.

The workflow is "take a directory and put it on the site". Addons is just the name for this directory on the site.

So we'll set up the tools to take "https://github.com/tensorflow/addons/tree/master/docs" and put it on the site as "tensorflow.org/addons".

So two things to remember about links for that:

1. Use relative links when linking between files within the directory (so users keep their github/colab/tensorflow.org context). Use full URLs if you need to link to something outside of the directory. Never use absolute path links.

2. In notebooks and markdown tfa.thing will be auto-linked to the appropriate api-page, if it exists.

[seanpmorgan]

Great thanks. So just to be clear will the utilized directory always come from master branch? At the moment we only generate docs for our release branches, but that'd probably require you pulling down a new directory for each release.

[seanpmorgan]

@MarkDaoust @lamberta Friendly bump on this question and then we can look to merge this. Are we required to have the latest releases API docs on our master branch?

[MarkDaoust]

Are we required to have the latest releases API docs on our master branch?

No, we've simplified the setup. There is now no requirement to have api_docs in you repo at all. When we generate the site, we'll run your build_docs.py script against your latest pip package, to generate the api_docs pages.

So just to be clear will the utilized directory always come from master branch?

Yes. While api reference material is generated from your pip package, we pull the rest of the docs from master so that doc-fixes don't need to wait for a release.

The one caution there is that notebooks demonstrating features for a future release need to be sure to pip install an appropriate nightly or preview package, but if you're test running things in colab, for example, that should be easy to remember.

[yashk2810]

As far as testing notebooks, @yashk2810 has some CI set up in the tensorflow/docs

Since a subsite is being created for addons, the notebooks will automatically get tested with the pipeline. If something fails, we will send an email to the addons team about the failure.

But there are a few things to keep in mind.

1. We test with TF2 and python3 by default. There are other options but it's not enabled by default.
2. Please follow the template
   https://github.com/tensorflow/docs/blob/master/tools/templates/notebook.ipynb to write the notebooks if it's not being written in this format.

Can you add the team's email where we can send the emails about failures?

[facaiy]

@yashk2810 please send failure to addons-testing@tensorflow.org , thanks, Yash!

1. We test with TF2 and python3 by default.

I'm fine, what do you think, Sean?

2. Please follow the template

Will do, thanks

[facaiy]

One more question, can we test notebook for master branch (I mean, tfa-nightly version)?

[yashk2810]

I mean, tfa-nightly

Yes, the infra will install whatever version you install in the notebook.

[seanpmorgan]

@yashk2810 please send failure to addons-testing@tensorflow.org , thanks, Yash!

1. We test with TF2 and python3 by default.

I'm fine, what do you think, Sean?

1. Please follow the template

Will do, thanks

Yes I agree this sounds good to me.

[MarkDaoust]

LGTM.