Question about markdown table format

General Discussion
, ,
#1

I have one question about markdown in git, and how it rendered in website.
for example,

source code is

Arguments Type Semantics
operand XlaOp Array to concatenate across

: : : replicas. :
| all_gather_dim | int64 | Concatenation dimension. |
| replica_groups | vector of vectors of | Groups between which the |
: : int64 : concatenation is performed. :
| channel_id | optional int64 | Optional channel ID for |
: : : cross-module communication. :

rendered in github is wrong

image
image772×480 23.7 KB

but rendered in website is right.

I read Contribuire alla documentazione di TensorFlow,
but find nothing about the format.

Can anyone help to solve my confusion?
how to follow markdown format in table?
is there any format tool?

any suggestions is welcome,
thanks in advance.

#2

Hello. Tables aren’t part of the original Markdown spec so different systems implemented their own syntax. For the TensorFlow docs, we optimize viewing for the webpage and use GitHub as a preview for convenience—but there are some Markdown discrepancies. Some pages can also be viewed in Colab.

Since the webpage renders correctly, please use that Markdown syntax for the table on that page. And, depending on the data and format, might just prefer a regular ole’ HTML table that renders everywhere. We use those, too.

2 Likes
#3

Hello billy

thanks for your reply.
I am still confused after read your message.

I want to contribute to tensorflow doc, but I have no idea about the markdown format in github.

there are 2 questions confused me.

1
the tensorflow website use html.
the doc in github use markdown.
who/how convert markdown to html?

I followed below commands, I get new files with suffix .md, but the .md file is html format actually.
and the .md file (html format) is different with the source code of website.

git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out

for example;
https://www.tensorflow.org/api_docs/python/tf/xla/experimental/jit_scope
this page’s source code, is not same with generated by above commands.

2
if I contribute to doc, i have to follow the format and style of markdown.
but I didn’t find the required rule about markdown for tensorflow github repo.
is there any formatter for markdown file before git push or PR in github?

BR.
Mingting

#5

Hi billy

I find there is _toc.yaml file in code. After investigate the _toc.yaml file.
I guess tensorflow website is generated with docfx tool, if this is true, this might answer my question#1.

I tried docfx, I can convert md to html, but I cannot get right table in html.
I guess, is there any privately markdown table extension used in google?

BR.
Mingting

1 Like
#6

The Markdown-to-HTML conversion for the website uses an internal system. As noted, there are a few discrepancies between the Markdown syntaxes, but the GitHub Markdown previewer and the Colab (Jupyter) preview will get you mostly there.

The generate2.py config script is used to generate the TensorFlow API reference documentation from Python docstrings. This Markdown should be viewable in GitHub and then we convert it to HTML in our docs publishing pipeline. It uses the api_generator module in our tensorflow-docs package. It’s actually a pretty nice Python API documentation system (and not TensorFlow specific), but not really documented. Many prefer it to Sphinx. But, yeah, this is for API docs only and not narrative docs.

2 Likes
#7

get it, thanks for your information.