Contributing to Documentation

# Install dependencies manually
pip install sphinx blurb python-docs-theme

# Build from Doc directory
sphinx-build -b html . build/html

# HTML for offline viewing
make html

# Open in browser after building
make htmlview

# HTML with live reload (Unix only)
make htmllive

# Plain text output
make text

# EPUB for e-readers
make epub

# LaTeX for PDF generation
make latex

# Check for broken links
make linkcheck

# Check for markup errors
make check

# Clean build files
make clean

cd Doc
make.bat html
make.bat htmlview

set PYTHON=C:\Path\To\python.exe
make.bat html

Main Title
==========

Section
-------

Subsection
^^^^^^^^^^

Subsubsection
~~~~~~~~~~~~~

This is a paragraph. Paragraphs are separated by blank lines.

*Italic text* and **bold text**.

``Inline code`` uses double backticks.

A literal block::

    def example():
        return "indented code block"

Python code:

.. code-block:: python

    def greet(name):
        """Greet someone."""
        print(f"Hello, {name}!")

C code:

.. code-block:: c

    static PyObject *
    greet(PyObject *self, PyObject *args)
    {
        /* C implementation */
    }

`External link <https://www.python.org/>`_

:ref:`Internal cross-reference <label-name>`

:func:`os.path.join` - Link to function
:class:`dict` - Link to class
:mod:`os` - Link to module
:pep:`8` - Link to PEP

Bulleted list:

* Item one
* Item two

  * Nested item
  * Another nested

* Item three

Numbered list:

#. First
#. Second
#. Third

Definition list:

Term
    Definition of the term

Another term
    Its definition

.. note::

    This is a note.

.. warning::

    This is a warning.

.. versionadded:: 3.15

.. versionchanged:: 3.15
    Description of the change.

.. deprecated:: 3.15
    Use :func:`new_function` instead.

:mod:`mymodule` --- Brief description
======================================

.. module:: mymodule
   :synopsis: Brief description.

.. moduleauthor:: Your Name <[email protected]>

**Source code:** :source:`Lib/mymodule.py`

--------------

Detailed description of the module.

.. function:: my_function(arg1, arg2)

   Description of the function.

   :param arg1: Description of arg1.
   :type arg1: str
   :param arg2: Description of arg2.
   :type arg2: int
   :return: Description of return value.
   :rtype: bool
   :raises ValueError: When arg1 is invalid.

.. class:: MyClass

   Description of the class.

   .. method:: method_name(param)

      Description of the method.

.. function:: open(file, mode='r', buffering=-1)

   Open file and return a corresponding file object.

   *file* is either a string or bytes object giving the pathname.

   *mode* is an optional string that specifies the mode in which
   the file is opened. It defaults to ``'r'``.

   :param file: Path to the file
   :type file: str or bytes
   :param mode: File opening mode
   :type mode: str
   :return: File object
   :rtype: file object
   :raises FileNotFoundError: If file doesn't exist

.. class:: MyClass(arg1, arg2=None)

   A class that does something.

   :param arg1: First argument
   :param arg2: Optional second argument

   .. attribute:: value

      The value attribute.

   .. method:: process(data)

      Process the data.

      :param data: Data to process
      :returns: Processed result

.. c:function:: PyObject* PyDict_New()

   Return a new empty dictionary, or *NULL* on failure.

   .. note::

      This function always succeeds in practice, but returns
      *NULL* for consistency with other APIs.

.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

   Insert *value* into the dictionary with the given *key*.

   :param p: Dictionary object
   :param key: Key object
   :param val: Value object
   :return: ``0`` on success, ``-1`` on failure

.. c:type:: PyDictObject

   This subtype of :c:type:`PyObject` represents a Python
   dictionary object.

.. c:member:: Py_ssize_t PyDictObject.ma_used

   Number of items in the dictionary.

Good:
    The :func:`open` function returns a file object.
    
Bad:
    open() returns a file object.

Good:
    :param str name: The name of the file
    :param int mode: File permissions (default: 0o644)
    
Bad:
    :param name: name

.. function:: greet(name)

   Print a greeting.

   Example::

       >>> greet("World")
       Hello, World!

cd Doc
make check

make linkcheck

# Build and open in browser
make htmlview

# Or manually
make html
open build/html/index.html  # macOS
xdg-open build/html/index.html  # Linux