apache
[Documentation] Migrate FAQ page to Sphinx / rst around release time
In ARROW-973, a Markdown page with the FAQ was added. When we are close to publishing a new version of the Sphinx site, it would make sense to move the FAQ to the main docs project and link from the project from page
Reporter: Wes McKinney / @wesm
Note: This issue was originally created as ARROW-5543. Please see the migration documentation for further details.
Luiz Irber: Note that you don't need to convert to RST, since Sphinx has support for markdown: http://www.sphinx-doc.org/en/master/usage/markdown.html
Wes McKinney / @wesm: What functional limitations does Markdown-in-Sphinx have? It seems support for cross-references has some issues
https://github.com/rtfd/recommonmark/issues/74
Neal Richardson / @nealrichardson:
What's the value of doing this? I think having a project-level FAQ at https://arrow.apache.org/faq/, rather than buried under /docs/ somewhere, is a good thing.
Antoine Pitrou / @pitrou: Generally, the value of putting things in the Sphinx docs is to add cross-navigation and make sure we don't have N doc entries for users. Also, we can also add top-level links from the Web site.
Joris Van den Bossche / @jorisvandenbossche: Do we still want to do this? I agree with Neal it seems to make sense to have those general FAQs on the main website.
It would be good to add anchors to that page, though, so you can actually link to one specific item (which is something that sphinx would do automatically)
Antoine Pitrou / @pitrou: I don't know, but I'll notice that the FAQ does not change often. Perhaps it doesn't need to.
Neal Richardson / @nealrichardson: Agree about adding anchors but presumably Jekyll can handle that.
IMO there is negative value in changing the URL of the FAQ, so I'm -1 on this. I'm open to being persuaded, but this issue is coming up on 2 years old now, and I haven't been persuaded yet ;)
This issue hasn't had activity in a long time. If it's still being worked on, please leave a comment. Otherwise, it will be closed on 23rd June.
Labelled Status: Stale-Warning for tracking.
