Sphinx 

Sphinx installation 

Open a new terminal/command prompt and follow steps below

Install sphinx for Ubuntu

sudo apt-get install python3-sphinx

Install sphinx for Window

pip install -U sphinx

Create document layout 

Run the command below to create

sphinx-quickstart docs

To configure layout, follow steps below

Separate source and build directories (y/n) [n]: Write y (without quotes) and press Enter.
Project name: Write your project`name (without quotes) and press Enter.
Author name(s): Write Your name (without quotes) and press Enter.
Project release []: Write year release (without quotes) and press Enter.
Project language [en]: Leave it empty (the default, English) and press Enter.

After that we will have the below structure in folder docs

    docs
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates

Create requirements 

Create a requirements.in file with content:

Sphinx>=5,<6
sphinx_rtd_theme

Create a requirements.txt file with content:

#
# This file is autogenerated by pip-compile with python 3.10
# To update, run:
#
#    pip-compile docs/requirements.in
#
alabaster==0.7.12
    # via sphinx
babel==2.10.3
    # via sphinx
certifi==2022.6.15
    # via requests
charset-normalizer==2.1.0
    # via requests
docutils==0.17.1
    # via
    #   sphinx
    #   sphinx-rtd-theme
idna==3.3
    # via requests
imagesize==1.4.1
    # via sphinx
jinja2==3.1.2
    # via sphinx
markupsafe==2.1.1
    # via jinja2
packaging==21.3
    # via sphinx
pygments==2.12.0
    # via sphinx
pyparsing==3.0.9
    # via packaging
pytz==2022.1
    # via babel
requests==2.28.1
# via sphinx
snowballstemmer==2.2.0
    # via sphinx
sphinx==5.0.2
    # via
    #   -r docs/requirements.in
    #   sphinx-rtd-theme
sphinx-rtd-theme==1.0.0
    # via -r docs/requirements.in
sphinxcontrib-applehelp==1.0.2
    # via sphinx
sphinxcontrib-devhelp==1.0.2
    # via sphinx
sphinxcontrib-htmlhelp==2.0.0
    # via sphinx
sphinxcontrib-jsmath==1.0.1
    # via sphinx
sphinxcontrib-qthelp==1.0.3
    # via sphinx
sphinxcontrib-serializinghtml==1.1.5
    # via sphinx
urllib3==1.26.9
    # via requests
furo==2021.11.16

Extensions 

Theme

Install the library

pip install sphinx-rtd-theme

In conf.py add the line below to extension:

'sphinx_rtd_theme'

In conf.py add the line below to html_theme:

"sphinx_rtd_theme"

Sphinx_copybutton

Install the library

pip install sphinx-copybutton

Then add the line below to requirements.txt

sphinx-copybutton

In conf.py add the line below to extension:

Sphinx-new-tab-link

Install the library

pip install sphinx-new-tab-link

Then add the line below to requirements.txt

sphinx-new-tab-link

In conf.py add the line below to extension:

'sphinx_new_tab_link'

Sphinx rtd dark mode

Install the library for Window

py -3 -m pip install sphinx-rtd-dark-mode

Install the library for Linux/OSX

python3 -m pip install sphinx-rtd-dark-mode

Then add the line below to requirements.txt

sphinx-rtd-dark-mode

In conf.py add the line below to extension:

'sphinx_rtd_dark_mode'

Sphinx Emoji codes

Install the library

pip install sphinxemoji

Then add the line below to requirements.txt

sphinxemoji

In conf.py add the line below to extension:

'sphinxemoji.sphinxemoji'

Then you can use emoji code replacements by writing them between bars:

This text includes a smiley face |:smile:| and a snake too! |:snake:|

Don't you love it? |:heart_eyes:|

If you want a consistent emoji style, you can set it in your conf.py file:

sphinxemoji_style = 'twemoji'

Sphinx favicon

Install the library

pip install sphinx-favicon

Then add the line below to requirements.txt

sphinx-favicon

In conf.py add the line below to extension:

'sphinx_favicon'

Then in conf.py file, add the lines below, favicon.png is an example image, you can use other images but remember to store it in _static folder:

favicons = [
{
    "sizes": "32x32",
    "href": "favicon.png",
}
]

Logo

Store logo image to _static folder. In conf.py file, add the line below:

html_logo = "_static/logo.png"

If you want to auto change logo, you have to put your wanted logo in _static folder. Then create a Java script file change_logo.js in _static folder with content:

document.addEventListener("DOMContentLoaded", function() {
var logo = document.querySelector(".wy-side-nav-search .logo");
if (logo) {
    var logos = ['_static/stitch.gif', '_static/c_stitch.gif']; // list of logo
    var currentIndex = 0; // Index of current logo

    setInterval(function() {
        currentIndex = (currentIndex + 1) % logos.length;
        logo.src = logos[currentIndex];
    }, 5000); // auto change logo after 5s
}
});

After that, create a layout.html in _templates folder (create your folder if you don`t have one) with content:

{% extends "!layout.html" %}

{% block sidebarlogo %}
<a href="{{ pathto(master_doc) }}" class="logo">
    <img id="logo" src="{{ pathto('_static/stitch.gif') }}" alt="{{ project }}">
</a>
{% endblock %}

Adjust window document

In _static folder, create custom.css file with content (width below is fullscreen):

/* make the page width fill the window */
.wy-nav-content {
max-width: none;
}

In conf.py file, below line html_static_path , add lines below:

def setup(app):
    app.add_css_file("custom.css")

Deploy to github 

Create a repository, set up in public.
Press creating a new file to create readme.txt file, then press commit change.
Press <>Code. Choose Add file, then choose Upload file. Pull folder docs to the repository.
Then Commit changes.
Choose Add file, then choose Create new file. Copy this .github/workflows/sphinx.yml then paste to make sphinx.yml file in .github folder.

In sphinx.yml file,add the contents below then press Commit change twice.

name: Build and Deploy Docs

on:
push:
    branches:
    - main
pull_request:

jobs:
build:
    runs-on: ubuntu-latest
    permissions:
        contents: write  # Necessary for deploying to GitHub Pages
    steps:
        - name: Checkout code
            uses: actions/checkout@v4

        - name: Set up Python
            uses: actions/setup-python@v2
            with:
            python-version: '3.10'  # Specify the desired Python version

        - name: Upgrade pip
            run: python -m pip install --upgrade pip

        - name: Install dependencies
            run: pip install -r docs/requirements.txt

        - name: Build the documentation
            run: sphinx-build -b html docs/source docs/build/html

        - name: Upload artifacts
            uses: actions/upload-artifact@v4
            with:
            name: html-docs
            path: docs/build/html/

        - name: Deploy to GitHub Pages
            uses: peaceiris/actions-gh-pages@v3
            if: github.ref == 'refs/heads/main'
            with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: docs/build/html

Press Settings, then choose Pages. Choose Deploy from branch. In select branch choose gh-pages, then press Save.
Refresh page and wait for 5 minutes to generate a web link.

Note

If you don`t see gh-pages then refresh page and do the step above again.

Clone document 

Delete your docs folder in your computer, then git clone the repository

git clone <github-document-url>

Build sphinx 

Open the folder cloned from github in Vscode. Then open the terminal and type the commands below

cd docs
make html

Add .gitignore file to docs folder, then put build to that file

Go to build/html/, copy the path of index.html file and paste to google-chrome

Otherwise on Ubuntu, just type the command below to the terminal

google-chrome build/html/index.html

Find layout sphinx_rtd_theme 

Invoke command below to find setting location of sphinx_rtd_theme (Window):

pip show sphinx-rtd-theme

Then find layout.html file.

References

[1]. Sphinx documentation

[2]. Sphinx Emoji codes