docs: Use sphinx-js

[abmusse]

Resolves #95

We now use sphinx-js for documentation.

[abmusse]

@kadler

I created an initial draft of docs using sphnix-js. Would you prefer to split this into multiple PRs?

If so I will split this out.

[kadler]

I think it's fine as-is. I set up a readthedocs project, but it's failing to build because sphinx-js is not installed by default. Can you add a docs/requirements.txt and add it to a (new) readthedocs config file.

Then, the build should work and we can preview/review the docs at https://nodejs-itoolkit.readthedocs.io/en/use-sphinx-js/

[abmusse]

@kadler I've added the requested files. Can you run another build?

[kadler]

Deprecated.js:iPgm(70):65: (WARNING/2) Explicit markup ends without a blank line; unexpected unindent.
Deprecated.js:iConn(549):93: (WARNING/2) Explicit markup ends without a blank line; unexpected unindent.
Deprecated.js:restConfig(529):12: (WARNING/2) Inline emphasis start-string without end-string.
Deprecated.js:restConfig(529):13: (WARNING/2) Inline emphasis start-string without end-string.

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/nodejs-itoolkit/envs/use-sphinx-js/lib/python3.7/site-packages/sphinx/cmd/build.py", line 304, in build_main
    app.build(args.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nodejs-itoolkit/envs/use-sphinx-js/lib/python3.7/site-packages/sphinx/application.py", line 341, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/nodejs-itoolkit/envs/use-sphinx-js/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 347, in build_update
    len(to_build))
  File "/home/docs/checkouts/readthedocs.org/user_builds/nodejs-itoolkit/envs/use-sphinx-js/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 360, in build
    updated_docnames = set(self.read())
  File "/home/docs/checkouts/readthedocs.org/user_builds/nodejs-itoolkit/envs/use-sphinx-js/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 472, in read
    self.env.doc2path(self.config.master_doc))
sphinx.errors.SphinxError: master file /home/docs/checkouts/readthedocs.org/user_builds/nodejs-itoolkit/checkouts/use-sphinx-js/docs/contents.rst not found

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/nodejs-itoolkit/checkouts/use-sphinx-js/docs/contents.rst not found

[abmusse]

Looks like we need to add master_doc = 'index' to conf.py readthedocs/readthedocs.org#2569 (comment)

@kadler Ok, I've specified the master_doc to be index.rst. Lets try another build.

[kadler]

The build has passed: https://nodejs-itoolkit.readthedocs.io/en/use-sphinx-js

[kadler]

I'd like to see the intro page be the pain page. Right now when you go to the docs you just get an index, which is not the best user experience / first impression.

[abmusse]

I'd like to see the intro page be the pain page. Right now when you go to the docs you just get an index, which is not the best user experience / first impression.

So I moved the contents of intro.rst into index.rst then ran a new build.

https://nodejs-itoolkit.readthedocs.io/en/use-sphinx-js/

[kadler]

FYI @abmusse there is a webhook setup already so any pushes automatically trigger a build.

[kadler]

Docs look pretty good. I think there's more improvements we can make, but definitely good enough to merge as they are. I'd rather get something up so that we can progress on #209 and other things.