Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save ganapathichidambaram/d7f07e24b209a41cf6aed02a9505eebd to your computer and use it in GitHub Desktop.
Save ganapathichidambaram/d7f07e24b209a41cf6aed02a9505eebd to your computer and use it in GitHub Desktop.
=========================================
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',
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment