What do you think about adding a Docs contributions and support links footer in every Docs webpage like in Github Docs
2 Likes
Nice idea.
Adding a footer link to either the /community landing page or /community/contribute page is straightforward. Not docs contribution-specific, but we could highlight on the landing page.
For individual pages we link to the GitHub location for API and notebook guides in the top buttons.
2 Likes
Yes, in Github Docs when we click “Make a Contribution” we are going to edit the page directly.
E.g. I think that now we cannot directly go with a click from the Website to Github locations of pages like Contribute to TensorFlow
1 Like
Ah, I see what you mean. docs.github.com looks like it’s organized under a central repo so this is a bit easier to pull off. Our docs are spread out across many repos (mostly to make it easier for teams to update) and not everything is in GitHub.
For notebooks, we lint check if there are buttons in the source files. And could potentially require this in plain Markdown files (though notebooks are the dominant documentation format on the website).
2 Likes
Unfortunately, I know this well and that was the point. 
In the case of TF as it is difficult for us to put a button it is also hard for a new user to manually chase the various Github repositories to understand where to contribute and what is the source that generated the page that he is reading.
1 Like
it is difficult for us to put a button it is also hard for a new user to manually chase the various Github repositories
Not sure I follow—all the notebooks on the website include (or should include) links to their source location in GitHub. For example, the GitHub button in this Addons tutorial points you to the correct repo location.
But we can’t use a specific link in the footer since the footer is site-wide.
1 Like
Yes I know but I am still talking about Markdown sources that we have on the website.
E.g. docs/code.md at master · tensorflow/docs · GitHub
Or Configuración de código de Visual Studio  | TensorFlow I/O
I don’t know, with the generating scripts, if it is easy to automatically know how many Markdown sources we are still consuming generating the Tensorflow website.
1 Like
Yes, I agree, buttons in the Markdown files would be useful.
We’ve been adding these buttons directly to the notebook file so they’re visible wherever the notebook is rendered: Colab, GitHub, website, or unrelated projects that aggregate notebooks. Could do something similiar for Markdown files. This is probably easiest and can be enforced in CI tests (GitHub Actions) using nblint or another check.
We can also think about auto-adding buttons in the docs pipeline when published to the website. Would be nice to standardize this across the site but requires docs infra work and not sure if we’d gain much over CI tests.
2 Likes
I think both solutions are viable.
In the meantime is there a quick trick to know how many Markdowns we currently use when we generate the TF website?
1 Like
Do we have any ticket in the repo to track this?
1 Like
Not across the entire site since it is assembled from multiple repos. But you can check an individual repo doc set:
$ cd tensorflow/docs
$ find site/en/ -name '*.md' \
| grep -v 'README.md\|sitemap.md' | grep -v '/r1/'
Since we’re unlikely to update the docs pipeline in the near future, we’ll have to explicitly add buttons to the top of the Markdown files. To enforce, would need to add CI checks to each repo which may be handled differently across projects—but would be straightforward for the tensorflow/docs repo. Also need to update the docs style guide.
Do we have any ticket in the repo to track this?
Don’t think so, but can file a feature request.
1 Like
Not across the entire site since it is assembled from multiple repos. But you can check an individual repo doc set:
Can we grep/print directly from the generator/assembler log? I suppose that we have a loop somewhere in the docs scripts.
1 Like
Jobs run independently and everything is converted to Markdown so can be difficult to determine the source format. But … we do have the en-snapshot directory in the tensorflow/docs-l10n repo—this is probably the closet thing to a single point of aggregation across docs projects.
1 Like
Ok so if it is all so distributed I think that the CI could check the Markdown file for the button and ping the source owner.
1 Like
P.s. on the en-snapshot we have 234 Markdown files.
So probably we have almost the same not directly editable pages in the website.
1 Like
if it is all so distributed I think that the CI could check the Markdown file for the button and ping the source owner
CI on the translations repo (or docs pipeline) would happen post-submit and would hold up publishing without fixing the source issue. This would also require some sort of notification system. Not impossible, but would likely need to be implemented on the OSS side.
1 Like
Ok, so we don’t have too much entry points to contribute on this.
1 Like
I don’t know if we have any roadmap about this old feature request but it could be also really useful if on some markdown generated pages we could have some reference/link related to the sources the genearated these pages and a note with the last run datetime.
E.g.
See our thread at: