New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[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_theme
for some time. An extension exists for limiting the depth, but would introduce a dependency.Preview Images
Long side bar:
R/Python border