Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
[docs] 📝 FAQ overhaul for linking to individual questions #2293
Fixes #2268. Individual questions can be linked to.
All sections now follow a new format (below).
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 side bar:
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... ```
StrikerRUS left a comment
@hayesall Wow, amazing! Many thanks!
Please update the anchors in links to fix the CI:
Also, it'll cool if you upgrade one another remaining link to FAQ so that it'll point to individual entry.
In addition, can you please elaborate what exactly is required to make FAQ links short? Maybe one example?
This can be accomplished through
**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
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
We are using old
I remember we pin old version exactly due to anchors false positive errors.