docs: add links to README (#12)

Author: kai687

README.md

@@ -5,38 +5,45 @@ replaces Sphinx's built-in search with Algolia DocSearch.
 
 ## Before you begin
 
-[**Apply for DocSearch**](https://docsearch.algolia.com/apply). You'll get an email with your Algolia credentials.
+[**Apply for DocSearch**](https://docsearch.algolia.com/apply).
+You'll get an email with your Algolia credentials.
 
 This extension supports Python versions 3.8, 3.9, 3.10, and 3.11 and Sphinx versions 5 and later.
 
 ## Install
 
-Install the `sphinx-docsearch` extension from PyPI:
+Install the `sphinx-docsearch` package:
 
 ```sh
 pip install sphinx-docsearch
 ```
 
 ## Configure
 
-1. Add `sphinx-docsearch` to your Sphinx configuration file `conf.py`:
+1. Add `sphinx-docsearch` to your Sphinx configuration:
 
    ```python
+   # conf.py
    extensions += ["sphinx_docsearch"]
    ```
 
 1. Add your Algolia credentials to your Sphinx configuration:
 
    ```python
+   # conf.py
    docsearch_app_id = "<DOCSEARCH_APP_ID>"
    docsearch_api_key = "<DOCSEARCH_SEARCH_API_KEY>"
    docsearch_index_name = "<DOCSEARCH_INDEX_NAME>"
    ```
 
-1. Optional: change configuration settings
+   See also: [Configure DocSearch](https://sphinx-docsearch.readthedocs.io/en/latest/configuration.html).
 
 ## Customize
 
-- Customize crawling (link to DocSearch or Crawler doc)
-- Add custom templates
-- Add custom CSS
+To change what the crawler should extract from your pages, see [Record Extractor](https://docsearch.algolia.com/docs/record-extractor).
+
+You can add [custom templates](https://sphinx-docsearch.readthedocs.io/en/latest/customization.html#add-custom-templates),
+if your Sphinx HTML theme uses templates [not provided](https://sphinx-docsearch.readthedocs.io/en/latest/themes.html)
+by this extension.
+
+You can customize the look of the DocSearch UI by [adding your own CSS](https://sphinx-docsearch.readthedocs.io/en/latest/customization.html#add-custom-css).

docs/conf.py

@@ -14,7 +14,7 @@
 
 # General configuration
 extensions = ["sphinx_docsearch", "myst_parser"]
-myst_enable_extensions = ["colon_fence"]
+myst_enable_extensions = ["colon_fence", "deflist"]
 
 # DocSearch Sphinx extension
 docsearch_app_id = os.getenv("DOCSEARCH_APP_ID")

docs/configuration.md

@@ -6,49 +6,41 @@ All configuration settings start with `docsearch_`.
 
 You **must** add at least your credentials to make DocSearch work:
 
-- **`docsearch_app_id`**
-
-  Your Algolia application ID.
+**`docsearch_app_id`**
+: Your Algolia application ID.
   You can find it in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys)
 
-- **`docsearch_api_key`**
-
-  Your Search API key.
+**`docsearch_api_key`**
+: Your Search API key.
   You can find it in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).
 
   :::{warning}
   Don't use your Write API key, which is used for crawling your content.
   :::
 
-- **`docsearch_index_name`**
-
-  The Algolia index name for your documentation.
+**`docsearch_index_name`**
+: The Algolia index name for your documentation.
 
 ## Optional configuration
 
 The Sphinx extension lets you configure these aspects of the DocSearch UI.
 
-- **`docsearch_container`** (default `#docsearch`)
-
-  The ID of the HTML element where the search input is added.
+**`docsearch_container`** (default `#docsearch`)
+: The ID of the HTML element where the search input is added.
   By default, the DocSearch input is added to the HTML element with the ID `docsearch`.
   You can change this setting if you're using a different theme.
 
-- **`docsearch_placeholder`** (default: `Search`):
-
-  The placeholder text for the search box.
-
-- **`docsearch_initial_query`**:
-
-  A query for an initial search if you want to show search results as soon as the user opens the search menu.
-
-- **`docsearch_search_parameters`**:
+**`docsearch_placeholder`** (default: `Search`)
+: The placeholder text for the search box.
 
-  Any Algolia search parameter you want to add.
+**`docsearch_initial_query`**
+: A query for an initial search if you want to show search results as soon as the user opens the search menu.
 
-- **`docsearch_missing_results_url`**:
+**`docsearch_search_parameters`**
+:  Any Algolia search parameter you want to add.
 
-  If specified, DocSearch adds a message to the "No results found" screen with the link to the URL you specified,
+**`docsearch_missing_results_url`**
+: If specified, DocSearch adds a message to the "No results found" screen with the link to the URL you specified,
   for users to report issues with missing search results.
   You can include the current search query as parameter ${query}. For example:
 

docs/what.md

@@ -3,11 +3,11 @@
 DocSearch is a program by Algolia for bringing fast and relevant search to every technical content for free.
 
 With DocSearch, Algolia indexes your documentation with a crawler.
-The Algolia Crawler comes with a dashboard, where you can configure what is crawled and you can schedule periodic updates.
+The Algolia Crawler comes with a dashboard, where you can configure what's crawled and you can schedule periodic updates.
 With your DocSearch credentials, you can access the Algolia dashboard,
 where you can see analytics about your Search and change the ranking of your search results.
 
-DocSearch also comes with a UI component that you can add o your website.
+DocSearch also comes with a UI component that you can add to your website.
 This Sphinx extension automatically adds it to your Sphinx project.
 
 :::{seealso}
@@ -27,7 +27,7 @@ To avoid having two different search interfaces on your website,
 this extension replaces the default search box provided by Sphinx.
 It overrides the built-in templates `searchbox.html` or `sidebar/search.html`.
 This makes the extension work with the [Furo](https://pradyunsg.me/furo/),
-[Read The Docs Sphinx Theme](https://sphinx-rtd-theme.readthedocs.io/en/stable/), and
+[Read The Docs](https://sphinx-rtd-theme.readthedocs.io/en/stable/), and
 [Alabaster](https://alabaster.readthedocs.io/en/latest/) themes by default.
 
 For these themes, the extension also adds custom CSS to make the DocSearch search box fit the theme.

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sphinx-docsearch"
-version = "0.0.2"
+version = "0.0.3"
 description = "A Sphinx extension for replacing the built-in search with Algolia DocSearch"
 authors = ["Algolia"]
 license = "MIT"

tests/test_config.py

@@ -11,7 +11,7 @@
 
 def test_returns_version() -> None:
     """It returns the correct version."""
-    assert sphinx_docsearch.__version__ == "0.0.2"
+    assert sphinx_docsearch.__version__ == "0.0.3"
 
 
 @pytest.mark.sphinx("html", confoverrides={"extensions": ["sphinx_docsearch"]})