[docs] 📝 FAQ overhaul for linking to individual questions

[hayesall]

Executive Summary

Fixes #2268. Individual questions can be linked to.

Overview

• Reformat "Contents" to use the .. contents:: directive
• Reword "Critical" into "Critical Issues"
• Reformat "Critical" section to define "critical issues" first
• Reformat FAQ sections to follow a new format (below)
• Reformat FAQ sections so individual questions have links

All sections now follow a new format (below).
A "frequently asked question" may also include a possible
cause and a solution (if the two are not obvious from
the context):

FAQ Section Title
=================

.. contents::
  :local:
  :backlinks: none

1. Question 1
-------------

**Possible Cause**: This is likely due to...

**Solution**: Fix with...

Some questions were renamed to try and make their contents more explicit. (e.g.: Python Package: Question 1). Many questions could begin with "I see an error message like this." Having more-explicit names could be helpful if the FAQ index gets longer, or if a person reads the index/greps for error messages.

Question 1: 

- I see error messages like this when install from GitHub using python setup.py install
+ Error: setup script specifies an absolute path when installing from GitHub using python setup.py install

Alternatives / Discussion Points

All feedback is appreciated! The following are some specific points that might warrant further discussion:

• Long questions are autogenerated with long links (e.g. FAQ.html#why-is-early-stopping-not-enabled-by-default-in-lightgbm). An alternative might be FAQ.html#general-12, but this might require setting more things manually.
• Each question is a subsection. This causes the side bar to have a large number of entries in the General section (see the preview image). This has been a known issue with sphinx_rtd_theme for some time. An extension exists for limiting the depth, but would introduce a dependency.
• The current formatting makes it a little hard to tell where one section ends and another begins (e.g. R to Python, see image below).

---

Preview Images

Long side bar:

R/Python border

[jameslamb]

thanks @hayesall ! I'll look more closely tomorrow

[StrikerRUS]

@hayesall Wow, amazing! Many thanks!

Please update the anchors in links to fix the CI:
https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#mingw-w64

https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#mingw-w64-2

Also, it'll cool if you upgrade one another remaining link to FAQ so that it'll point to individual entry.
https://github.com/microsoft/LightGBM/blob/7da11ffeacf79be81839431b1cbc7c293ba7d9bd/python-package/README.rst#build-with-mingw-w64-on-windows

In addition, can you please elaborate what exactly is required to make FAQ links short? Maybe one example?

Long questions are autogenerated with long links (e.g. FAQ.html#why-is-early-stopping-not-enabled-by-default-in-lightgbm). An alternative might be FAQ.html#general-12, but this might require setting more things manually.

[hayesall]

In addition, can you please elaborate what exactly is required to make FAQ links short? Maybe one example?

Long questions are autogenerated with long links (e.g. FAQ.html#why-is-early-stopping-not-enabled-by-default-in-lightgbm). An alternative might be FAQ.html#general-12, but this might require setting more things manually.

This can be accomplished through :ref: tags.

For example:

**Contents**

- :ref:`general-1`
- :ref:`general-2`

.. _general-1:

1. Where do I find more details about LightGBM parameters?
----------------------------------------------------------

(answer)

.. _general-2:

2. Another Question
-------------------

(answer)

All occurrences of general-1 are replaced with the title ("1. Where do I..."), and the html hyperlink is: FAQ.html#general-1

I like how the hyperlinks look, but the solution is a bit fragile and the FAQ.html#where-do-i-find-more-details-about-lightgbm-parameters are still valid links.

[hayesall]

Still failing a check-docs test, looking into it.

[StrikerRUS]

Still failing a check-docs test, looking into it.

It's linkchecker issue. Never mind! I'll re-run the tests till it pass.

[StrikerRUS]

This can be accomplished through :ref: tags. ...

Ah, I see. Thanks!
It requires manual edition of contents section too each time new entry is added, right?..

[hayesall]

It requires manual edition of contents section too each time new entry is added, right?..

Yep.

It's linkchecker issue.

Sphinx's make linkcheck is also raising an error on my local machine (below). Maybe GitHub tweaked something on their backend and now the links aren't behaving the same?

Warning, treated as error:
/Users/hayesall/LightGBM/docs/FAQ.rst.rst:289:broken link:
https://github.com/microsoft/LightGBM/blob/master/python-package/README.rst#build-from-sources
(Anchor 'build-from-sources' not found)
make: *** [linkcheck] Error 2

[StrikerRUS]

Sphinx's make linkcheck is also raising an error on my local machine (below). Maybe GitHub tweaked something on their backend and now the links aren't behaving the same?

We are using old LinkChecker 8.6 Copyright (C) 2000-2013 Bastian Kleineidam linkchecker on the CI. Maybe this is the reason? Because on CI the error is about YouTube:

URL        `https://www.youtube.com/watch?v=iqzXhp5TxUY'
Name       `here'
Parent URL file:///home/travis/build/microsoft/LightGBM/docs/_build/html/Parallel-Learning-Guide.html, line 262, col 119
Real URL   https://www.youtube.com/watch?v=iqzXhp5TxUY
Check time 0.531 seconds
D/L time   0.568 seconds
Size       1KB
Info       Redirected to
           `https://www.google.com/sorry/index?continue=https://www.youtube.com/watch%3Fv%3DiqzXhp5TxUY&q=EgRoxoM6GKiegeoFIhkA8aeDS518C8SE-j-34lK4u8ejzutjLzF1MgFy'.
Warning    [http-empty-content] No Content
Result     Valid: 204 No Content

I remember we pin old version exactly due to anchors false positive errors.

[StrikerRUS]

LGTM! Many thanks for this contribution!

[jameslamb]

Looks great! Thank you so much!