<commit_before>##############################################
Documentation using Sphinx and ReadTheDocs.org
##############################################

Without documentation, however wonderful your software, other potential
adopters and developers simply won't be very interested in it.

The good news is that there are several tools that will make presenting and
publishing it very easy, leaving you only to write the content and mark it up
appropriately.

For documentation, we'll use **Sphinx** to generate it, and **Read the Docs**
to publish it. GitHub will be a helpful middleman.

If you have a package for which you'd like to create documentation, you might
as well start producing that right away. If not, you can do it do it in a new
dummy project.

Set up your working environment
===============================

The virtualenv
--------------

As usual, create and activate a new virtualenv::

    $ virtualenv documentation-tutorial
    [...]
    $ cd documentation-tutorial/
    $ source bin/activate


The package or project
----------------------

If you have an existing package to write documentation for
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If your package is on GitHub already and you want to start writing documention
for, clone it now using Git. And of course, start a new branch::

    git checkout -b first-docs

You can merge your docs into your master branch when they start to look
respectable.

If you don't have an existing package that needs docs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you don't have a suitable existing package on GitHub, you'll need to create
a repository on GitHub the way you did before. Call it ``my-first-docs``. Then
create a Git repository locally::

    $ mkdir my-first-docs
    $ cd my-first-docs/
    $ git init
    $ git remote add origin git<EMAIL>:<your git username>/my-first-docs.git

Create a ``docs`` directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^

And either way, create a ``docs`` directory for your docs to live in::

    $ mkdir docs

Sphinx
======

Install Sphinx
--------------

::

    pip install sphinx

It might take a minute or so, it has quite a few things to download and install.
<commit_msg>Remind people to create a new branch<commit_after>##############################################
Documentation using Sphinx and ReadTheDocs.org
##############################################

Without documentation, however wonderful your software, other potential
adopters and developers simply won't be very interested in it.

The good news is that there are several tools that will make presenting and
publishing it very easy, leaving you only to write the content and mark it up
appropriately.

For documentation, we'll use **Sphinx** to generate it, and **Read the Docs**
to publish it. GitHub will be a helpful middleman.

If you have a package for which you'd like to create documentation, you might
as well start producing that right away. If not, you can do it do it in a new
dummy project.

Set up your working environment
===============================

The virtualenv
--------------

As usual, create and activate a new virtualenv::

    $ virtualenv documentation-tutorial
    [...]
    $ cd documentation-tutorial/
    $ source bin/activate


The package or project
----------------------

If you have an existing package to write documentation for
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If your package is on GitHub already and you want to start writing documention
for, clone it now using Git. And of course, start a new branch::

    git checkout -b first-docs

You can merge your docs into your master branch when they start to look
respectable.

If you don't have an existing package that needs docs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you don't have a suitable existing package on GitHub, you'll need to create
a repository on GitHub the way you did before. Call it ``my-first-docs``. Then
create a Git repository locally, point it at GitHub, and create a new branch
for your work::

    $ mkdir my-first-docs
    $ cd my-first-docs/
    $ git init
    $ git remote add origin <EMAIL>:<your git username>/my-first-docs.git
    $ git checkout -b first-docs

Create a ``docs`` directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^

And either way, create a ``docs`` directory for your docs to live in::

    $ mkdir docs

Sphinx
======

Install Sphinx
--------------

::

    pip install sphinx

It might take a minute or so, it has quite a few things to download and install.

{'fraction_non_alphanumeric': 0.18468667255075022, 'fraction_numerical': 0.0, 'mean_word_length': 3.801906779661017, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3587771', 'n_tokens_mistral': 1184, 'n_tokens_neox': 1123, 'n_words': 596}