[docs] move wiki to Read the Docs #945

StrikerRUS · 2017-09-29T16:54:17Z

The main aim of this PR is to move remained wiki pages to docs folder and to Read the Docs in consequence. So all documentation is in one place and wiki could be deleted now.
Also some references have been added to easier navigation through the documentation.
In all README files headings have been refactored to the same type (all capital letters).

Please review Installation-Guide.rst with more attention - I added some sections about GUI compilation with Visual Studio there.
It would be great if someone could help me find out how to made Read the Docs deal with links with anchors and not to break everything.
Also, there is file gcc-tips.Rmd in docs folder on which there are no references. Where it's better to insert the reference to it?
And I want to ask @Laurae2 continue updating LightGBM/docs/Key-Events.md file - it's very useful thing.

StrikerRUS · 2017-09-29T19:17:41Z

docs/Experiments.rst

+GPU Experiments
+---------------
+
+Refer to `GPU Performance <./GPU-Performance.rst>`__.


I've found out that many urls in new doc files (no matter md or rst) couldn't be resolved locally on my machine with make html: they converted to something like LightGBM/docs/_build/html/GPU-Performance.rst or even https://github.com/Microsoft/LightGBM/tree/master/docsInstallation-Guide.md.

Maybe someone knowns WAIDW?

The problem starts to be more precise. Now links from only rst files are not converted to html.

It was just a typo in md file which was resulted in broken url.

I've understood that rst documents are not processed by recommonmark and passed as is. So, my solution is based on js function which allows keep actual links at GitHub (e.g. ./Features.md) and at Read the Docs replace them with .html.

do you really need the extension of .rst?

@henry0312 Yeah! I decided to convert from md to rst after I found your comment.
Now I have plans (not in this PR) convert all files to rst, so we'll be able to create the documentation without recommonmark which are not compatible with the latest Sphinx (see #958).

To be honest, I think that ReadTheDocs + GitHub repo is quite enough. I suppose, GitHub Pages is excess thing, GitHub itself renders current rst files rather good (markdown is saved and all cross links are working between files), you may take a look to my branch to see it works.

Yeah, I saw this Sphinx documentation. Unfortunately, such style of links doesn't work at GitHub repo - we need to provide file extensions anyway.

OK, I'll check your branch.

By the way, when you convert md to rst, you can use Pandoc (although you already used it) like this:

pandoc --columns=200 -f markdown_github -t rst -o hoge.rst hoge.md (may need to adjust `columns`)

Great! Please also when you will review my branch

Please review Installation-Guide.rst with more attention - I added some sections about GUI compilation with Visual Studio there.

Thanks for your suggestion! Unfortunately, I had problems with Pandoc installation and decided to use online variant with further validation.

Please review Installation-Guide.rst with more attention - I added some sections about GUI compilation with Visual Studio there.

I don't know if the sections are right or wrong because I don't have Windows.
@guolinke, can you help us?

StrikerRUS · 2017-10-01T14:09:12Z

Since we anyway need _static folder in docs, I decided to store images locally in the repo (they are not heavy) for more independence, because some images were hosted on GitHub, other - on http://www.huan-zhang.com/

guolinke · 2017-10-02T01:35:21Z

@StrikerRUS can you also update the wiki to make them consistent ?
Or put replace the content in the wiki with the link to the new place.

StrikerRUS · 2017-10-02T01:53:19Z

@guolinke In my opinion, the best thing is do the same as this.

StrikerRUS · 2017-10-05T12:23:37Z

@Laurae2 Where should I insert the reference to gcc-tips.Rmd file?

henry0312 · 2017-10-05T15:55:15Z

docs/FAQ.md

-* [@wxchan](https://github.com/wxchan) (Python package)
+* [@guolinke](https://github.com/guolinke) (C++ code / R-package / Python-package)
+* [@Laurae2](https://github.com/Laurae2) (R-package)
+* [@wxchan](https://github.com/wxchan) (Python-package)


I think you also should be here 😄

Thanks 😃

BTW, why you aren't there?

I don't know, but I will be glad if you add me in this PR :)

Sure! I'll definitely add you in this PR.

C++ code / Python-package?

Just Python-package, please
because I don't understand over half of cpp codes :p
(though I can read and wrire c++)

henry0312 · 2017-10-07T08:14:40Z

docs/_static/js/rst_links_fix.js

@@ -0,0 +1,4 @@
+window.onload = function() {


Did you check the rst_links_fix.js to work on built documentations (or Read The Doc) ?

I checked it locally on my machine - all seems to be OK.
On Travis it's done by emulation of this js function.

Since it's jQuery, it should work with all browsers. In theory...

okay.

In theory...

yeah, in theory 😅

henry0312 · 2017-10-07T08:19:45Z

Almost all of the changes look good to me.
Please fix conflict.

StrikerRUS · 2017-10-07T08:57:18Z

Sorry, I'm away from my computer. I'll ping you after update.
Nevertheless, we are waiting the answer about Installation Tutorial on Windows.

guolinke · 2017-10-07T09:30:16Z

@Laurae2 can you answer StrikerRUS's question ?

Laurae2 · 2017-10-07T09:36:30Z

@Laurae2 Where should I insert the reference to gcc-tips.Rmd file?

What do you mean by "where"? (I'm 2 weeks behind on this repo so I'm not sure what happened)

Nevertheless, we are waiting the answer about Installation Tutorial on Windows.

Which one?

And I want to ask @Laurae2 continue updating LightGBM/docs/Key-Events.md file - it's very useful thing.

Missing time here.

StrikerRUS · 2017-10-07T09:42:45Z

@Laurae2

What do you mean by "where"? (I'm 2 weeks behind on this repo so I'm not sure what happened)

Now this document has no references at itself from other ones. I want to fix this situation. Does it document is relevant to only R-users?

Nevertheless, we are waiting the answer about Installation Tutorial on Windows.
Which one?

This question is for @guolinke: #945 (comment)

Laurae2 · 2017-10-07T09:45:11Z

@StrikerRUS It is relevant for any user using gcc and not wanting to use the default optimization flags (such as using precompiled packages for different Intel generation with different extra instruction sets), especially for those using linux.

StrikerRUS · 2017-10-07T09:50:24Z

@Laurae2 Got it, thank you!

guolinke · 2017-10-07T13:18:17Z

docs/Installation-Guide.rst

+
+3. Go to ``LightGBM-master/windows`` folder.
+
+4. Open ``LightGBM.sln`` file with Visual Studio, choose ``Release`` configuration and click ``BUILD-> Build Solution (Ctrl+Shift+B)``.


need to select X64 as well ?

There is no another choice neither at start windows, nor in project settings:

StrikerRUS · 2017-10-07T16:49:28Z

@guolinke I replaced wiki pages with corresponding links to Read the Docs.

* fixed Python-API references * moved Features section to ReadTheDocs * fixed index of ReadTheDocs * moved Experiments section to ReadTheDocs * fixed capital letter * fixed citing * moved Parallel Learning section to ReadTheDocs * fixed markdown * fixed Python-API * fixed link to Quick-Start * fixed gpu docker README * moved Installation Guide from wiki to ReadTheDocs * removed references to wiki * fixed capital letters in headings * hotfixes * fixed non-Unicode symbols and reference to Python API * fixed citing references * fixed links in .md files * fixed links in .rst files * store images locally in the repo * fixed missed word * fixed indent in Experiments.rst * fixed 'Duplicate implicit target name' message which is successfully resolved by adding anchors * less verbose * prevented maito: ref creation * fixed indents * fixed 404 * fixed 403 * fixed 301 * fixed fake anchors * fixed file extentions * fixed Sphinx warnings * added StrikerRUS profile link to FAQ * added henry0312 profile link to FAQ

StrikerRUS added 19 commits September 29, 2017 00:05

fixed Python-API references

3e86aab

moved Features section to ReadTheDocs

74e110a

fixed index of ReadTheDocs

1c9a627

moved Experiments section to ReadTheDocs

4a51ea9

fixed capital letter

a501910

fixed citing

c978cbb

moved Parallel Learning section to ReadTheDocs

4ac8c5d

fixed markdown

1dd5843

fixed Python-API

f88db7f

resolved conflicts

8f4e1a3

fixed link to Quick-Start

3bb8cdf

fixed gpu docker README

fd40037

moved Installation Guide from wiki to ReadTheDocs

6dd389e

removed references to wiki

1e94983

fixed capital letters in headings

4115cee

hotfixes

44c9d58

fixed non-Unicode symbols and reference to Python API

6485ca1

fixed citing references

e7e37e7

Merge branch 'master' into readthedocs

07b5fa7

StrikerRUS commented Sep 29, 2017

View reviewed changes

guolinke requested a review from henry0312 September 30, 2017 06:16

StrikerRUS added 5 commits September 30, 2017 20:44

Merge branch 'master' into readthedocs

caa067e

fixed links in .md files

5c8bb27

fixed links in .rst files

8180b8c

Merge branch 'master' into readthedocs

5aa7c11

store images locally in the repo

71b0900

fixed missed word

1f5386a

StrikerRUS added 4 commits October 5, 2017 02:29

fixed 301

ae494d4

fixed fake anchors

61b0629

fixed file extentions

f8c7a7a

fixed Sphinx warnings

3516ec9

henry0312 reviewed Oct 5, 2017

View reviewed changes

StrikerRUS added 4 commits October 5, 2017 19:56

Merge branch 'master' into readthedocs

5bbf9f4

added StrikerRUS profile link to FAQ

c772b34

Merge branch 'master' into readthedocs

9438114

Merge branch 'master' into readthedocs

abfcfbf

henry0312 reviewed Oct 7, 2017

View reviewed changes

guolinke reviewed Oct 7, 2017

View reviewed changes

StrikerRUS added 3 commits October 7, 2017 17:29

added henry0312 profile link to FAQ

a118fb0

Merge remote-tracking branch 'origin/readthedocs' into readthedocs

e21e280

Merge branch 'master' into readthedocs

dd92661

guolinke approved these changes Oct 7, 2017

View reviewed changes

guolinke merged commit 6d34fb8 into microsoft:master Oct 7, 2017

StrikerRUS deleted the readthedocs branch October 7, 2017 20:04

guolinke mentioned this pull request Oct 18, 2017

[docs] documentation improvement #976

Merged

StrikerRUS mentioned this pull request Jul 27, 2019

Change FAQs in docs so we can link to individual questions #2268

Closed

lock bot locked as resolved and limited conversation to collaborators Mar 11, 2020


		3. Go to ``LightGBM-master/windows`` folder.

		4. Open ``LightGBM.sln`` file with Visual Studio, choose ``Release`` configuration and click ``BUILD-> Build Solution (Ctrl+Shift+B)``.

[docs] move wiki to Read the Docs #945

[docs] move wiki to Read the Docs #945

Conversation

StrikerRUS commented Sep 29, 2017

StrikerRUS Sep 29, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StrikerRUS Oct 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StrikerRUS commented Oct 1, 2017 • edited Loading

guolinke commented Oct 2, 2017

StrikerRUS commented Oct 2, 2017

StrikerRUS commented Oct 5, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

henry0312 Oct 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

henry0312 Oct 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StrikerRUS Oct 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

henry0312 commented Oct 7, 2017

StrikerRUS commented Oct 7, 2017

guolinke commented Oct 7, 2017

Laurae2 commented Oct 7, 2017

StrikerRUS commented Oct 7, 2017 • edited Loading

Laurae2 commented Oct 7, 2017

StrikerRUS commented Oct 7, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StrikerRUS commented Oct 7, 2017

StrikerRUS Sep 29, 2017 •

edited

Loading

StrikerRUS Oct 5, 2017 •

edited

Loading

StrikerRUS commented Oct 1, 2017 •

edited

Loading

henry0312 Oct 7, 2017 •

edited

Loading

henry0312 Oct 7, 2017 •

edited

Loading

StrikerRUS Oct 7, 2017 •

edited

Loading

StrikerRUS commented Oct 7, 2017 •

edited

Loading