Incorrect rendering of tables in the docs

[plamut]

In the generated docs, the tables containing "applicable previous versions" are not rendered correctly, while in the source markdown file UPGRADING.md they are rendered just fine.

[meredithslota]

Not yet closed, let's wait to see if the change actually makes it's way through. :)

[meredithslota]

Ok, the change has not yet made it's way through despite v3.6.1 being released. Turns out I don't totally understand our doc generation process. Tagging in @tswast for advice here — am I missing some important connective tissue here?

[tswast]

I think it's a limitation of the Sphinx markdown renderer (https://stackoverflow.com/questions/44461762/sphinx-is-not-recognising-my-markdown-tables/50616143). I'll try treating the file as ReStructured Text, since that is better supported.

[tswast]

The "UPGRADING" guide no longer appears in https://cloud.google.com/python/docs/reference/datacatalog/latest

I think we'll still need #268 once it's added back, but passing on to folks who might know about the reference docs on cloud.google.com.

[dandhlee]

I've excluded because of formatting issues as well. Once #268 is added I'll try running it through the plugin to see how it'd look and go from there.

[tswast]

Thanks @dandhlee

I'll pass back to you once I solve the Owlbot issue with #268

[dandhlee]

I can see the well formatted html page being generated with Sphinx for HTML. With the existing tools it doesn't seem like I can pull that page nicely for cloud.google.com. I'll have to add some feature support from Sphinx to the plugin, will get back to this in few days.

[meredithslota]

Honestly, I'm not sure this is worth the effort — I'm considering instead rolling back the changes that originally caused the funky formatting (the insertion of a formatted table) and instead just presenting that content in text since it's relatively simple. That would require undoing #268 and the related change in synthtool googleapis/synthtool#1285 but might be easier than the remaining work. Thoughts?

[tswast]

IMO, Cloud RAD really needs to support full Sphinx formatting. I don't believe this is the only doc that has been excluded for this reason.

[tswast]

I filed bug 212403496 internally to handle the Sphinx formatting issues in general. For now, passing back to @meredithslota to tackle reverting the Markdown -> ReStructured Text conversion and removing the problematic tables.

[meredithslota]

Reopening just to remind me to confirm that this actually fixes the issue.

[meredithslota]

Confirmed fixed as of 3.6.2 release HUZZAH.