misc docs improvements

README.rst

@@ -5,10 +5,17 @@ Krank
 
 Fetch psychology datasets from remote sources.
 
-**Krank** is a single-stop for using publicly available remote datasets. It offers simplified downloading, storing, version controlling, loading into Python, minimal/corrective pre-processing, and in some cases, data harmonization of various datasets. This project has a huge dependency on the `Pooch <https://www.fatiando.org/pooch` Python package, which makes retrieving and storing any remote file incredibly easy.
+.. important::
 
+   Refer to `Krank's online documentation <https://remrama.github.io/krank>`_ for the most comprehensive and up-to-date description of features and functions.
 
-.. warning:: This project is in the planning stage of development. Don't use it.
+
+**Krank** is a single-stop for using publicly available remote datasets. It offers simplified downloading, storing, version controlling, loading into Python, minimal/corrective pre-processing, and in some cases, data harmonization of various datasets. This project has a huge dependency on the `Pooch <https://www.fatiando.org/pooch>`_ Python package, which makes retrieving and storing any remote file incredibly easy.
+
+
+.. warning::
+
+   This project is in the planning stage of development. Don't use it.
 
 
 **Krank** currently has a limited set of modules that are each dedicated to a specific type of dataset. The topical focus of these datasets is probably *psychology* or *cognitive neuroscience*. The datasets are grouped into separate modules for organizational purposes, where each module focuses on a specific type of dataset. Each module functions almost identically, and the separation of fetching functions into these separate modules is primarily for organizational purposes.
@@ -20,6 +27,16 @@ Currently implemented modules include:
 * ``liwc``: Fetch previously published or shared LIWC scores/output.
 
 
+
+Installation
+------------
+
+.. code-block:: shell
+
+   pip install --upgrade krank
+
+
+
 Usage
 -----
 
@@ -36,17 +53,10 @@ An identical way to fetch the same file is through krank's top-level interface,
 
 .. code-block:: python
 
-    import krank
-
-    df = krank.fetch_lexicon("threat")
-
+   import krank
 
-Installation
-------------
-
-.. code-block:: shell
+   df = krank.fetch_lexicon("threat")
 
-   pip install krank
 
 
 Contributing

docs/conf.py

@@ -44,6 +44,7 @@
     "sphinx.ext.intersphinx",  # Link to other project's documentation (see mapping below)
     # "sphinx_autodoc_typehints",  # Automatically document param types (less noise in class signature)
     # "numpydoc",
+    # "sphinx_copybutton",  # Adds a copy button to code blocks (for pasting)
     "sphinx.ext.autosectionlabel",
     # "sphinx.ext.linkcode",
 ]
@@ -151,8 +152,8 @@
 
 # configure sphinx-copybutton
 # https://github.com/executablebooks/sphinx-copybutton
-copybutton_prompt_text = r">>> |\.\.\. |\$ "
-copybutton_prompt_is_regexp = True
+# copybutton_prompt_text = r">>> |\.\.\. |\$ "
+# copybutton_prompt_is_regexp = True
 
 
 # -- Options for autosummary/autodoc output ------------------------------------
@@ -172,6 +173,7 @@
 # -- Intersphinx ------------------------------------------------
 
 intersphinx_mapping = {
+    "krank": ("https://remrama.github.io/krank", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
     "pooch": ("https://www.fatiando.org/pooch/latest", None),
     "python": ("https://docs.python.org/3", None),

docs/index.rst

@@ -7,24 +7,65 @@
 Krank
 =====
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents
 
-   api.rst
+Fetch psychology datasets from remote sources.
+
+**Krank** is a single-stop for using publicly available remote datasets. It offers simplified downloading, storing, version controlling, loading into Python, minimal/corrective pre-processing, and in some cases, data harmonization of various datasets. This project has a huge dependency on the `Pooch <https://www.fatiando.org/pooch>`_ Python package, which makes retrieving and storing any remote file incredibly easy.
+
+See Krank's :doc:`api` for a complete list of currently available functions.
+
+
+.. warning::
+
+   This project is in the planning stage of development. Don't use it.
+
+
+
+Installation
+------------
+
+.. code-block:: shell
+
+   pip install krank
+
 
 
 Modules
 -------
 
-* :ref:`api:tables`
-* :ref:`api:lexicons`
-* :ref:`api:liwc`
+**Krank** currently has a limited set of modules that are each dedicated to a specific type of dataset. The topical focus of these datasets is probably *psychology* or *cognitive neuroscience*. The datasets are grouped into separate modules for organizational purposes, where each module focuses on a specific type of dataset. Each module functions almost identically, and the separation of fetching functions into these separate modules is primarily for organizational purposes. Currently implemented modules include:
+
+* :ref:`api:tables`: Fetch tables that were manually extracted from journal publications.
+* :ref:`api:lexicons`: Fetch lexicons that contain vocabularies with associated numerical scores.
+* :ref:`api:liwc`: Fetch previously published or shared LIWC scores/output.
+
+
+
+Usage
+-----
+
+Fetch (i.e., download) the `threat` LIWC dictionary, described in `Choi et al., 2022, PNAS <https://doi.org/10.1073/pnas.2113891119>`_  and shared publicly via `Michele Gelfand's personal website <https://www.michelegelfand.com/threat-dictionary>`_.
+
+.. code-block:: python
+
+   from krank import lexicons
+
+   df = lexicons.fetch_threat()
+
+
+An identical way to fetch the same file is through krank's top-level interface, which offers a more general way to retrieve datasets and might be more convenient for looping over a large number of datasets to load them systematically.
+
+.. code-block:: python
+
+   import krank
+
+   df = krank.fetch_lexicon("threat")
+
+
 
+Contributing
+------------
 
-Indices and tables
-------------------
+Currently, Krank is developed mostly for my own personal desires for more convenient data access, more convenient data storage, a better ability to see a high-level view of all the datasets available for my projects, and better version-control over the public datasets I use and create. Making a Python package with documentation to view the datasets seemed like the best way to do this.
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+That being said, if anyone else finds it useful and wants to contribute, please do. Feel free to post questions, bugs, feature requests, new dataset proposals, or even new module proposals on the `Krank GitHub Issues page <https://github.com/remrama/krank/issues>`_.