Sphinx tutorial

sphinx_doc.txt

$ sphinx-quickstart 

In conf.py add the path of the project as follows
sys.path.insert(0, os.path.abspath('/home/pavan/code/kafka_project'))

# to generate rst files from modules, use the following command
$ sphinx-apidoc -o build_docs/api/ -f /home/pavan/code/kafka_project/framework

To build the module use the following command in root_directory of sphinx where conf.py, static and templates files are included.
$ sphinx-build . _build/


# By default sphinx wont create docstring for class constructor. we need to explicitly add the following in conf.py
autoclass_content = 'both'

# By default docstring generated for methods are sorted by aplhabetical. if we need to change to exactly how methods are defined,
we need to use the following in conf.py
autodoc_member_order = 'bysource'

# Add the below line in conf.py for cross reference warnings

class PatchedPythonDomain(PythonDomain):
    def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
        if 'refspecific' in node:
            del node['refspecific']
        return super(PatchedPythonDomain, self).resolve_xref(
            env, fromdocname, builder, typ, target, node, contnode)


def setup(sphinx):
    sphinx.override_domain(PatchedPythonDomain)