Setting up proper documentation with Sphinx docs — Building stocksimpy 1

Hi there! If you are new to this series, “Building stocksimpy” is a series where I create a new Python library from scratch, documenting every step along the way. The goal of the library is to be a lightweight, open-source, and well-documented alternative to other stock strategy testing libraries.

It’s a journey for me to learn Python, improve my software engineering skills, and explore data science.

Why Set Up Sphinx Docs Now?

One of my main goals with stocksimpy is to keep the codebase beginner-friendly and maintainable. That means having great documentation from day one.

Instead of manually writing Markdown and trying to keep the documentation updated every time I make a small change, I decided to use Sphinx, a powerful tool to auto-generate HTML documentation for Python code’s docstrings.

What is Sphinx?

Sphinx is a documentation generator that pulls information directly from your code, and Sphinx docs automatically detect all of your docstrings in your .py files. Then, it generates an HTML file containing all of your documentation in an organized manner. It is widely used in the Python ecosystem, including major libraries like NumPy, pandas, and scikit-learn.

It might seem like a small help, but in reality, constantly updating your documentation as you build new functions or changing the documentation that you already wrote is hard to maintain. And making all this look good at the same time just becomes a headache. Sphinx does all this for you so you can focus on writing your code.

How to Set up Sphinx?

First, locate the directory that contains your project. Then, to set up Sphinx docs, I would suggest creating a new folder called docs. This helps keep everything organized.

Locate the docs directory, and then if you haven’t downloaded Sphinx before, run the following line(s):

Create Virtual Environment(recommended):

python -m venv venv

Activate the virtual environment

• On Windows:

venv\Scripts\activate.bat

• On Linux/macOS:

source venv/bin/activate

Install Sphinx

pip install spinx

If you want to, like I did, you can install a popular theme like sphinx_rtd_theme:

pip install sphinx_rtd_theme

Setting up Spinx

To get started, you can run the following line:

sphinx-quickstart

This will ask you the following questions:

• Separate source and build directories (y/n): Generally, saying y is a good choice as it keeps your directory cleaner, which is also what I did.
• Project name, author, version, release: Fill these in as appropriate. If this is your first release, you could say 0.1.0
• autodoc: automatically insert docstrings from modules (y/n) [n]: If you’re documenting Python code and want to automatically pull in docstrings, choose y. This is highly recommended for Python projects.

After answering these questions, Sphinx is going to create a set of files. After that, your docs directory looks something like this:

Configuring conf.py

All the information you just answered is stored in conf.py, and you can edit it as you wish. Here are some things to check: project, copyright, author, version, release.

extensions: This list defines which Sphinx extensions are active. If you chose autodoc during quickstart, it should be there. Here are some others you might want to add:

• sphinx.ext.autodoc: for Python docstring
• sphinx.ext.napolean: if you use Google or NumPy style docstrings, I will show you an example
• sphinx.ext.viewcode: adds links to source code
• sphinx.ext.intersphinx: to link to the documentation of other Sphinx projects Here is an example extensions that I used in stocksimpy:

If you also installed the sphinx_rts_theme I mentioned for a more modern look:

html_theme = 'sphinx_rtd_theme'

And finally, at the top of your conf.py you should have the following code:

import os
import sys
sys.path.insert(0, os.path.abspath('LINK_TO_YOUR_CODE')

Fill in LINK_TO_YOUR_CODE wherever your code is located. (Mine is “../../src”)

Add Content

You can write your documentation in reStructuredText(.rst).

• index.rst is your main entry point. It contains toctree(table of contents tree) directive to link to other documentation files. Here is an example from my code:

• For these references you need to create new .rst files and in my case, I create api.rst file (in source). In your other reference .rst files you can directly bind it to a module, and it documents it for you!

Here is my api.rst:

API Reference
=============

.. automodule:: stocksimpy.data_handler
   :members:

.. automodule:: stocksimpy.indicators
   :members:

data_handler and indicators are the names of my modules inside of my packages (stocksimpy).

Build Your Documentation

Now you just need to run the following command in docs directory:

make html

• On windows:

.\make.bat html

Then it should create your documentation in _build\html.

And that’s it, you now have documentation for your code.

Next Steps

After setting up Sphinx, you can use Read the Docs to publish your documentation online. If your project is open-source, you can share your documentation with everyone for free.

Setting up Read the Docs shouldn’t be hard, as you just need to point your GitHub repo — or I think they are okay with a couple of other platforms — and they do the rest.

Reflections

Setting up Sphinx early on gave me more structure and helped me think about how others might use stocksimpy in the future. It’s tempting to skip documentation at the beginning, but tools like Sphinx make it easy and rewarding.

What’s Next?

In the next post, I’ll start building the main file structure as well as some basic indicators like SMA and RSI.

---

🚀 Follow the Journey

If you’re into Python, finance, open-source, or just love watching a dev project unfold — stick around!

building stocksimpy series

• 🐈‍⬛ Star this on GitHub
• 🧠 Follow me on Twitter / X
• 🔷 I’m now on Bluesky
• 📰 Or read more of my posts on Medium
• 💬 Let’s connect on LinkedIn

Thanks for reading — let me know how you would document your code, or would you use sphinx too.