Merge pull request #1199 from remotestorage/feature/sphinx_typedoc

Fix SphinxJS/TypeDoc integration

.gitignore

@@ -9,4 +9,5 @@ server/server-state
 server-state
 doc/code
 doc/_build
+doc/__pycache__/
 /remotestorage*.js

.readthedocs.yml

@@ -0,0 +1,6 @@
+version: 2
+
+python:
+  version: 3.8
+  install:
+    - requirements: doc/requirements.txt

doc/conf.py

@@ -43,7 +43,7 @@
 
 # Used to extract JSDoc function/class docs from source
 js_language = 'typescript'
-js_source_path = '../src'
+js_source_path = '../src/'
 jsdoc_config_path = '../tsconfig.json'
 primary_domain = 'js'
 
@@ -184,3 +184,10 @@
      author, 'remoteStoragejs', 'One line description of project.',
      'Miscellaneous'),
 ]
+
+#
+# HACKFIX WARNING
+# TODO Remove this when there is official support for pre-build steps on RTD
+# https://github.com/readthedocs/readthedocs.org/issues/6662
+#
+os.system('npm install')

doc/contributing/docs.rst

@@ -3,22 +3,22 @@ Documentation
 
 The documentation for remoteStorage.js is generated from `reStructuredText
 <http://docutils.sourceforge.net/rst.html>`_ files in the ``doc/`` folder, as
-well as `JSDoc <http://usejsdoc.org/>`_ code comments, which are being pulled
+well as `TypeDoc <https://typedoc.org/>`_ code comments, which are being pulled
 in via special declarations in those files.
 
 We use `Sphinx <http://www.sphinx-doc.org/>`_ to generate the documentation
 website, and the `sphinx-js <https://pypi.python.org/pypi/sphinx-js/>`_
-extension for handling the JSDoc part.
+extension for handling the TypeDoc part.
 
-How to write reStructuredText and JSDoc
----------------------------------------
+How to write reStructuredText and TypeDoc
+-----------------------------------------
 
 For learning both the basics and advances features of reStructuredText, we
 highly recommend the `reStructuredText Primer
 <http://www.sphinx-doc.org/en/stable/rest.html>`_ on the Sphinx website.
 
-For JSDoc, you can find an intro as well as a detailed directive reference `on
-their official website <http://usejsdoc.org/>`_.
+For TypeDoc, you can find guides as well as a detailed reference `on
+the project's website <https://typedoc.org/>`_.
 
 Automatic builds and publishing
 -------------------------------
@@ -55,12 +55,12 @@ Build
 
 Run the following command to automatically watch and build the documentation::
 
-   $ npm run doc
+   $ npm run autobuild-docs
 
-This will start a web server, serving the HTML docs on `<http://localhost:8000>`_.
+This will start a web server, serving rendered HTML docs on `<http://localhost:8000>`_.
 
 .. HINT::
-   The autobuild cannot watch for changes in JSDoc comments as of now, so you
+   The autobuild cannot watch for changes in TypeDoc comments as of now, so you
    will need to re-run the command, or change something in a ``.rst`` file in
    order for code documentation changes to be re-built.
 

doc/contributing/github-flow.rst

@@ -87,7 +87,7 @@ Reviewing pull requests
 -  Check if it works, if it has unit tests, if the tests pass, and if
    JSHint and CodeClimate are happy.
 -  Check if the code is understandable, with clear and unambiguous names for
-   functions and variables, and that it has JSDoc comments and a changelog
+   functions and variables, and that it has TypeDoc comments and a changelog
    entry.
 -  If you use ``git up``, like recommended above, it will automatically
    create tracked branches for all remote branches. So in order to

doc/contributing/internals/cache-data-format.rst

@@ -27,7 +27,7 @@ will get either its 'local' revision if it exists, or its 'common'
 revision otherwise. The following are versioning tree diagrams of how
 local and remote revisions of a node can interact:
 
-::
+.. CODE:: text
 
     //in sync:
     1)  . . . . [common]

doc/cordova.rst

@@ -21,11 +21,6 @@ as the redirect URL during the OAuth flow.
 When a user connects their storage, the OAuth dialog will open in an
 in-app browser window, set to show the address to prevent phishing attacks.
 
-.. image:: ../_images/cordova_oauth.png
-   :width: 188px
-   :align: right
-   :alt: Screenshot of the OAuth dialog
-
 After the user authorizes the app, the server will redirect to the
 configured redirect URL with the authorization token added as a
 parameter. remoteStorage.js will intercept this redirect, extract the

doc/js-api/remotestorage.rst

@@ -4,14 +4,14 @@ RemoteStorage
 Constructor
 -----------
 
-Create a ``remoteStorage`` instance like so::
+Create a ``remoteStorage`` class instance like so::
 
-   var remoteStorage = new RemoteStorage();
+   const remoteStorage = new RemoteStorage();
 
 The constructor can optionally be called with a configuration object. This
 example shows all default values::
 
-   var remoteStorage = new RemoteStorage({
+   const remoteStorage = new RemoteStorage({
      cache: true,
      changeEvents: {
        local:    true,
@@ -27,7 +27,7 @@ example shows all default values::
 .. NOTE::
    In the current version, it is only possible to use a single
    ``RemoteStorage`` instance. You cannot connect to two different remotes yet.
-   We intend to support this soon (see issue :issue:`991`)
+   We intend to support this eventually (see issue :issue:`991`)
 
 .. WARNING::
    For the change events configuration, you currently have to set all events
@@ -138,13 +138,10 @@ List of events
 """"""""""""""""""""""""
    Emitted when the sync interval changes
 
-Prototype functions
--------------------
+List of functions
+-----------------
 
-The following functions can be called on your ``remoteStorage`` instance:
-
-.. autofunction:: RemoteStorage#authorize(options)
-  :short-name:
+The following methods/functions can be called on your ``remoteStorage`` instance:
 
 .. autofunction:: RemoteStorage#connect(userAddress, [token])
   :short-name:

doc/requirements.txt

@@ -1,4 +1,4 @@
-sphinx-js >= 3.0
+sphinx-js >= 3.1
 sphinx-issues
 sphinx-autobuild
 sphinx_rtd_theme