Merge branch 'master' of https://github.com/executablebooks/sphinx-comments

Author: choldgraf

doc/dokieli.md

@@ -1,10 +1,13 @@
-# dokieli
+# Dokieli
 
 ```{raw} html
 <script src="https://dokie.li/scripts/dokieli.js"></script>
 <link media="all" rel="stylesheet" type="text/css" href="https://dokie.li/media/css/dokieli.css" />
 ```
 
+Dokieli is an open source comments and annotation engine that follows web standards and allows you to have full control over where your comments are aggregated and who has access.
+
+Dokieli is activated on this page. You can see the web overlay by clicking on the hamburger menu in the upper-right corner of this page.
 
 ## Activate `dokie.li`
 

doc/hypothesis.md

@@ -1,11 +1,13 @@
 # Hypothesis
 
-test
-
 ```{raw} html
 <script async="async" src="https://hypothes.is/embed.js"></script>
 ```
 
+Hypothesis is a centralized web services that allows you to comment and annotate arbitrary web pages across the web.
+
+Hypothesis is activated on this page. You can see the web overlay by clicking on the `<` button in the upper-right corner of this page.
+
 ## Activate `hypothes.is`
 
 You can activate `hypothes.is` by adding the following to your `conf.py` file:
@@ -18,4 +20,4 @@ comments_config = {
 
 This will add a [hypothes.is overlay](https://web.hypothes.is/) to your documentation. This extension simply activates the hypothes.is javascript bundle on your Sphinx site. This will cause the hypothes.is overlay to be shown, allowing your readers to log-in and comment on your documentation if they have questions.
 
-When you build your documentation, you will see the hypothes.is overlay to the right of your screen.
+When you build your documentation, you will see the hypothes.is overlay to the right of your screen.

doc/index.md

@@ -8,14 +8,15 @@ Currently, these commenting engines are supported:
 - [utteranc.es](https://utteranc.es/) is a web commenting system that uses GitHub Issues to store and manage comments.
 - [`dokie.li`](https://dokie.li/) is an open source commenting and annotation overlay built on web standards.
 
+For examples of each service, as well as instructions for how to activate it,
+click on the links to the left.
+
 ## Installation
 
 Clone and install the github reposiory
 
 ```bash
-git clone https://github.com/choldgraf/sphinx-comments
-cd sphinx-comments
-pip install -e .
+pip install git+https://github.com/choldgraf/sphinx-comments
 ```
 
 Next, activate the extension by adding it to your `conf.py` file:
@@ -27,7 +28,15 @@ html_extensions = [
 ]
 ```
 
+## Configuration
+
+To configure `sphinx-comments` (and to choose the engine you'd like to use),
+you should configure the `comments_config` dictionary in `conf.py`. Instructions
+for doing so can be found in the page for each of the supported engines below.
+
 ```{toctree}
+:caption: Supported engines
+:maxdepth: 2
 hypothesis
 dokieli
 utterances

doc/utterances.md

@@ -1,4 +1,8 @@
-# Utterance
+# Utterances
+
+Utterances is a commenting engine built on top of GitHub issues. It embeds a comment box in your page that users (with a GitHub account) can use to ask questions. These become comments in a GitHub issue in a repository of your choice.
+
+Utterances is activated on this page. You can see the comment box at the bottom of the page's content. Click the "log in" button and you'll be able to post comments!
 
 ## Activate `utteranc.es`
 
@@ -33,4 +37,4 @@ When you build your documentation, pages will now have a comment box at the bott
    label="💬 comment"
    crossorigin="anonymous"
 />
-```
+```