Docs centered on ReadTheDocs instead of GitHub #2949
Conversation
|
This basically makes ReadTheDocs the source of truth and slims down the main README to avoid linking into GitHub where possible. We need to write usage docs for the .NET bindings, and then after that things should be mostly self contained on RTD. There's one or two links to the native client README for building from source but that should be it. Hopefully this solves #2824 by redirecting people to instructions that work reliably with the latest released model by default. We may still want to have release branches as we go into maintenance of 1.x, but we don't have to keep changing the default branch on GitHub. Built docs are here: https://community-tc.services.mozilla.com/api/queue/v1/task/Kh_P4l6jRZ6AP0o4skMJPA/runs/0/artifacts/public/doc-html.zip |
SUPPORT.rst
Outdated
| @@ -4,14 +4,10 @@ Contact/Getting Help | |||
| There are several ways to contact us or to get help: | |||
|
|
|||
|
|
|||
| #. | |||
| `\ **FAQ** <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ - We have a list of common questions, and their answers, in our `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_. When just getting started, it's best to first check the `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ to see if your question is addressed. | |||
| #. `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ - We have a list of common questions, and their answers, in our `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_. When just getting started, it's best to first check the `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ to see if your question is addressed. | |||
There was a problem hiding this comment.
Do we really want to keep the wiki? I feel like nobody reads it.
There was a problem hiding this comment.
Yeah, I was thinking about that, we don't check or maintain the FAQ often enough. Should probably just tell people to search Discourse and the issue tracker.
| @@ -65,7 +65,7 @@ If you have a capable (NVIDIA, at least 8GB of VRAM) GPU, it is highly recommend | |||
| pip3 uninstall tensorflow | |||
There was a problem hiding this comment.
General comment on this file. Should the github reference on line 126 be re-worded as you did with the other github references?
There was a problem hiding this comment.
How do you feel about embedding a full listing of the flag definitions in a page?
There was a problem hiding this comment.
If it's generated from the code, why not.
There was a problem hiding this comment.
Addressed in the new commit. Built docs: https://community-tc.services.mozilla.com/api/queue/v1/task/Qvo2k34eSDS-GMDQMt5WCg/runs/0/artifacts/public/doc-html.zip
|
|
||
| Installing bindings from source | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| If pre-built binaries aren't available for your system, you'll need to install them from scratch. Follow these :github:`native client installation instructions <native_client/README.rst>`. | ||
| If pre-built binaries aren't available for your system, you'll need to install them from scratch. Follow the :github:`native client build and installation instructions <native_client/README.rst>`. |
There was a problem hiding this comment.
Do we want to/can we not link to GitHub here?
There was a problem hiding this comment.
I think ideally we move the build instructions to ReadTheDocs as well.
| @@ -1,4 +1,4 @@ | |||
| Full project description and documentation on GitHub: [https://github.com/mozilla/DeepSpeech](https://github.com/mozilla/DeepSpeech). | |||
| Full project description and documentation on [https://deepspeech.readthedocs.io/](https://deepspeech.readthedocs.io/). | |||
There was a problem hiding this comment.
Not a note on this file but hasn't native_client/java/README.md been forgotten?
There was a problem hiding this comment.
The Java README is more akin to the native_client README or the dotnet README, where it's mostly about development and building rather than using of pre-built binaries. We need to write the usage instructions for them, and then add those to RTD too.
|
Addressed immediate comments, will work on Java and .NET stuff in follow up PRs. |
No description provided.