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
Merged

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

merged 3 commits into from Jul 31, 2019

Conversation

hayesall
Copy link
Contributor

@hayesall 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
Copy link
Collaborator

@jameslamb jameslamb commented Jul 30, 2019

thanks @hayesall ! I'll look more closely tomorrow

Copy link
Collaborator

@StrikerRUS 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
Copy link
Contributor Author

@hayesall 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
Copy link
Contributor Author

@hayesall hayesall commented Jul 30, 2019

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

@StrikerRUS
Copy link
Collaborator

@StrikerRUS 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
Copy link
Collaborator

@StrikerRUS 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
Copy link
Contributor Author

@hayesall 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
Copy link
Collaborator

@StrikerRUS 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.

Copy link
Collaborator

@StrikerRUS StrikerRUS left a comment

LGTM! Many thanks for this contribution!

Copy link
Collaborator

@jameslamb jameslamb left a comment

Looks great! Thank you so much!

@StrikerRUS StrikerRUS merged commit 04a5601 into microsoft:master Jul 31, 2019
4 checks passed
@hayesall hayesall deleted the faq branch Aug 3, 2019
@lock lock bot locked as resolved and limited conversation to collaborators Mar 11, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants