Skip to content

talkable/talkable-docs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

3d9fe08 · Jan 9, 2025
May 28, 2024
Dec 9, 2020
Jan 9, 2025
Mar 6, 2017
Sep 28, 2014
Nov 12, 2024
Jul 30, 2014
May 28, 2024
Apr 1, 2014
Feb 14, 2022
Jan 24, 2023
Jan 9, 2025
May 28, 2024
Sep 16, 2024
Aug 13, 2014

Repository files navigation

Talkable Documentation

Build Status

This GitHub repository represents Talkable’s documentation site, located at docs.talkable.com.

The Talkable documentation uses reStructuredText as its markup language and is built using Sphinx.

Sphinx

For more details see The Sphinx Documentation.

reStructuredText

For more details see The reST Quickref.

Sections

Section headings are very flexible in reST. We use the following convention in the Talkable documentation:

  • # for module headings
  • = for sections
  • - for subsections
  • . for subsubsections

Cross-referencing

Sections that may be cross-referenced across the documentation should be marked with a reference. To mark a section use .. _ref-name: before the section heading. The section can then be linked with :ref:`ref-name`. These are unique references across the entire documentation.

For example:

.. _talkable-module:

Talkable Module
###############

This is the module documentation.

.. _talkable-section:

Talkable Section
================

Talkable Subsection
-------------------

Talkable Subsubsection
......................

Here is a reference to "talkable section": :ref:`talkable-section` which will have the
name "Talkable Section".

Coding Guidelines for Documentation

General Formatting Rules

  1. Directives (.. syntax):
  • All directives starting with .. (e.g., .. image::, .. note::) must have 2 spaces indentation for their content. Examples:

    .. image:: /_static/img/example.jpg
      :alt: Example Image
    
    .. note::
      This is an important note.
  1. Meta Directives (.. meta::):
  • For .. meta:: blocks, use 3 spaces for the content indentation. Example:

    .. meta::
       :description: This is an example of a meta directive.
  1. Code Blocks (.. code-block::):
  • Code inside .. code-block:: must have 2 spaces indentation. Example:

    .. code-block:: html
      <h1>Hello world!</h1>

Empty Line at the End of Files

Always ensure there is a blank line at the end of each file to adhere to formatting standards.

Build the documentation

First install Sphinx. See below.

Installing Sphinx on macOS

  • Install Homebrew.

  • Install Ruby and Bundler, and run bundle install to install dependencies.

  • Install Python (>= 3.9) and pip:

    brew install python
    

    More information in case of trouble: https://docs.brew.sh/Homebrew-and-Python

  • Install dependencies:

    pip3 install -r requirements.txt --break-system-package
    

    If you have problems, try adding -I flag (--ignore-installed) to the pip install command.

If you get the error "unknown locale: UTF-8" when generating the documentation, the solution is to define the following environment variables:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Building

Run rake preview from "master" branch.

Setting up LiveReload

Run rake server from "master" branch and open http://localhost:5000 in browser.

Deploying

If you’re deploying for the first time make sure you have gh-pages branch locally. Otherwise run the following command to create it: git checkout -b gh-pages origin/gh-pages.

General flow:

  1. Pull changes from master
  2. Checkout your new branch from master
  3. Make changes
  4. Deploy your changes to staging (see the instruction below)
  5. Create a Pull Request to "master" branch, providing the demo URL to the changed page in Pull Request’s description.
  6. Merge pull request once it passes the review
  7. Deploy

If you did everything right, deploying is as easy as rake deploy from "master" branch.

Deploying to Staging

If it’s your first time deploying to staging, run rake setup to setup git remote.

  1. Switch to local branch "void" and pull the latest changes from the remote: git checkout void; git pull
  2. Merge your branch into local branch "void": git merge YOUR_BRANCH_NAME
  3. Push the changes to the remote branch "void": git push origin void
  4. Deploy: rake deploy:staging

See "master" branch: https://github.com/talkable/talkable-docs

See "gh-pages" branch: https://github.com/talkable/talkable-docs/tree/gh-pages

See GitHub Page (auto generated): https://docs.talkable.com