Sphinx Installation and configuration-Linux

=========================================
Sphinx Installation & Configuration
=========================================

-------------------------------
Sphinx Installation
-------------------------------

In redhat distribution to install sphinx package should be available in the name of python-sphinx. 
Use below command to install sphinx package.

.. code-block :: console

    yum install python-sphinx

    
To Verify the Installation use below command. 

.. code-block :: console
   
    which sphinx-quickstart


For PDF Output you need to install the *texlive* package by using mentioned command on redhat distribution.

.. code-block :: console

    yum install texlive*


PIP Installation
----------------------------

pip python based package installer required setuptools dependencies. To install by source code are :

.. code-block :: console

    wget https://pypi.python.org/packages/source/s/setuptools/setuptools-7.0.tar.gz --no-check-certificate
    tar xzf setuptools-7.0.tar.gz
    cd setuptools-7.0/
    python setup.py install

To Install a pip by downloading a latest pip source code.:

.. code-block :: console

    cd
    wget https://bootstrap.pypa.io/get-pip.py
    python get-pip.py

Once after successful Installation to verify the pip by checking the version.

.. code-block :: console

    pip --version

sphinx_rtd_theme Installation 
---------------------------------

sphinx_rtd_theme is the thirdparty HTML theme for sphinx based documentation. We can install by using pip package installer.

.. code-block :: console
    
    pip install sphinx_rtd_theme



Do the following changes on */usr/lib/python2.7/site-packages/sphinx/quickstart.py* file to implement the *sphinx_rtd_theme*
as default templates for the sphinx documentation.

Add the following line on initial stage on the file before html related option.

.. code-block :: python

    import sphinx_rtd_theme


Change the html_theme option value from *default* to *sphinx_rtd_theme*

.. code-block :: python

    html_theme = "default"
    
    to
    
    html_theme = "sphinx_rtd_theme"

Enter the html_theme_path value as sphinx_rtd_theme.get_html_theme_path().

.. code-block :: python

    html_theme_path = []
    
    to
    
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

And do the mentioned following changes to remove the sphinx copyright informattion.

.. code-block :: python

    html_show_sphinx = True 
    
    to
    
    html_show_sphinx = False

To Disable the *view source* link on HTML

.. code-block :: python

    #html_show_sourcelink = True
    
    to
    
    html_show_sourcelink = False

And change the latex_documents option mentioned below to remove the indices and blank pages before that.

.. code-block :: python

    latex_documents = [
        ('%(master_str)s', '%(project_fn)s.tex', u'%(project_doc_texescaped_str)s',
        u'%(author_texescaped_str)s', 'manual'),
    ]

to

.. code-block :: python

    latex_documents = [
        ('%(master_str)s', '%(project_fn)s.tex', u'%(project_doc_texescaped_str)s',
        u'%(author_texescaped_str)s', 'manual',True),
    ]

Do the following changes on this file (*/usr/lib/python2.7/site-packages/sphinx/writers/latex.py*) to remove the blank Pages before and after Contents page.

.. code-block :: python

    'babel':           '\\usepackage{babel}',

    to

    'babel':           '\\usepackage[english]{babel}',


Add this openany,oneside value under classoptions in the *writers/latex.py* file under default_elements category.

.. code-block :: python

    'classoptions':    ',openany,oneside',