Skip to content
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鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] 馃摑 FAQ overhaul for linking to individual questions #2293

Merged
merged 3 commits into from Jul 31, 2019

Conversation

@hayesall
Copy link
Contributor

hayesall commented Jul 29, 2019

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

Screen Shot 2019-07-29 at 6 38 37 PM

Long side bar:

Screen Shot 2019-07-29 at 6 39 11 PM

R/Python border

Screen Shot 2019-07-29 at 7 01 15 PM

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...
```
@jameslamb

This comment has been minimized.

Copy link
Collaborator

jameslamb commented Jul 30, 2019

thanks @hayesall ! I'll look more closely tomorrow

Copy link
Collaborator

StrikerRUS left a comment

@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
image

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

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
image

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.

docs/FAQ.rst Outdated Show resolved Hide resolved
@hayesall

This comment has been minimized.

Copy link
Contributor Author

hayesall commented Jul 30, 2019

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.

Add period to `2. Error messages: ....`
Fix links to FAQ in Installation-Guide.rst
@hayesall

This comment has been minimized.

Copy link
Contributor Author

hayesall commented Jul 30, 2019

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

@StrikerRUS

This comment has been minimized.

Copy link
Collaborator

StrikerRUS commented Jul 30, 2019

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 comment has been minimized.

Copy link
Collaborator

StrikerRUS commented Jul 30, 2019

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?..

docs/Installation-Guide.rst Outdated Show resolved Hide resolved
@hayesall

This comment has been minimized.

Copy link
Contributor Author

hayesall commented Jul 30, 2019

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
Drop general FAQ link in `Installation-Guide.rst`
Add FAQ question links to `python-package/README.rst`
@StrikerRUS

This comment has been minimized.

Copy link
Collaborator

StrikerRUS commented Jul 30, 2019

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.

@hayesall hayesall requested review from chivee, henry0312 and wxchan as code owners Jul 30, 2019
Copy link
Collaborator

StrikerRUS left a comment

LGTM! Many thanks for this contribution!

Copy link
Collaborator

jameslamb left a comment

Looks great! Thank you so much!

@StrikerRUS StrikerRUS merged commit 04a5601 into microsoft:master Jul 31, 2019
4 checks passed
4 checks passed
Microsoft.LightGBM #20190730.3 succeeded
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
license/cla All CLA requirements met.
Details
@hayesall hayesall deleted the hayesall:faq branch Aug 3, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can鈥檛 perform that action at this time.