[docs] 📝 FAQ overhaul for linking to individual questions
#2293
Conversation
Reformat "Contents" to use the `.. contents::` directive Reword "Critical" into "Critical Issues" Reformat "Critical" section to define "critical issues" Reformat FAQ sections to follow a new format 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): ```rst Section Title ============= .. contents:: :local: :backlinks: none 1. Question 1 ------------- **Possible Cause**: This is likely due to... **Solution**: Fix with... ```
|
thanks @hayesall ! I'll look more closely tomorrow |
@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.
This can be accomplished through 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 I like how the hyperlinks look, but the solution is a bit fragile and the |
Add period to `2. Error messages: ....` Fix links to FAQ in Installation-Guide.rst
|
Still failing a |
It's |
Ah, I see. Thanks! |
Yep.
Sphinx's 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 |
Drop general FAQ link in `Installation-Guide.rst` Add FAQ question links to `python-package/README.rst`
We are using old I remember we pin old version exactly due to anchors false positive errors. |
Executive Summary
Fixes #2268. Individual questions can be linked to.
Overview
.. contents::directiveAll 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):
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.
Alternatives / Discussion Points
All feedback is appreciated! The following are some specific points that might warrant further discussion:
FAQ.html#why-is-early-stopping-not-enabled-by-default-in-lightgbm). An alternative might beFAQ.html#general-12, but this might require setting more things manually.sphinx_rtd_themefor some time. An extension exists for limiting the depth, but would introduce a dependency.Preview Images
Long side bar:
R/Python border