Atlantic.Net Blog

How to Install Sphinx-Doc on Ubuntu 20.04

Hitesh Jethva
by Atlantic.Net (228 posts) under Dedicated Server Hosting, Tutorials
0 Comments

Sphinx is a powerful documentation generator tool that allows you to create intelligent and beautiful documentation. It is written in python and based on the jinja template. Sphinx has many features that make it easier to generate web pages, printable PDFs, and ePub documents.

In this post, we will show you how to install Sphinx-Doc on Ubuntu 20.04.

Prerequisites

  • A fresh Ubuntu 20.04 server on the Atlantic.Net Cloud Platform
  • A root password configured on your server

Step 1 – Create Atlantic.Net Cloud Server

First, log in to your Atlantic.Net Cloud Server. Create a new server, choosing Ubuntu 20.04 as the operating system with at least 2GB RAM. Connect to your Cloud Server via SSH and log in using the credentials highlighted at the top of the page.

Once you are logged in to your Ubuntu 20.04 server, run the following command to update your base system with the latest available packages.

apt-get update -y

Step 2 – Install Required Dependencies

Sphinx-Doc is written in Python, so you will need to install Python modules and Apache server to your system. You can install all of them with the following command:

apt-get install python3-pip python3-dev python3-setuptools apache2 -y

Once all the packages are installed, update pip to the latest version with the following command:

pip3 install --upgrade pip

Step 3 – Install Sphinx-Doc

Next, you can install the Sphinx-Doc using the pip command as shown below:

pip3 install sphinx

Once the installation has been finished, you should get the following output:

Installing collected packages: MarkupSafe, Jinja2, sphinxcontrib-jsmath, Pygments, sphinxcontrib-devhelp, docutils, imagesize, snowballstemmer, alabaster, sphinxcontrib-serializinghtml, sphinxcontrib-htmlhelp, pytz, babel, sphinxcontrib-applehelp, pyparsing, packaging, sphinxcontrib-qthelp, sphinx
Successfully installed Jinja2-2.11.3 MarkupSafe-1.1.1 Pygments-2.8.1 alabaster-0.7.12 babel-2.9.0 docutils-0.16 imagesize-1.2.0 packaging-20.9 pyparsing-2.4.7 pytz-2021.1 snowballstemmer-2.1.0 sphinx-3.5.3 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-htmlhelp-1.0.3 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.4

Step 4 – Configure Sphinx-Doc

Next, change the directory to Apache document root and run the Sphinx-Doc setup script.

cd /var/www/html/
sphinx-quickstart

You will be asked to provide your project name, author name, and project release as shown below:

Welcome to the Sphinx 3.5.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: n

The project name will occur in several places in the built documentation.
> Project name: myapp
> Author name(s): admin
> Project release []: 20.04

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: 

Creating file /var/www/html/conf.py.
Creating file /var/www/html/index.rst.
Creating file /var/www/html/Makefile.
Creating file /var/www/html/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /var/www/html/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Next, run the following command to generate a static HTML file:

make html

You should get the following output:

Running Sphinx v3.5.3
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                 
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

The above command will generate an HTML file at /var/www/html/_build/html/index.html.

Step 5 – Configure Apache for Sphinx-Doc

Next, you will need to edit the Apache default virtual host configuration file and define the path of your HTML file.

nano /etc/apache2/sites-available/000-default.conf

Find the following lien:

DocumentRoot /var/www/html/

And, replaced it with the following line:

DocumentRoot /var/www/html/_build/html/

Save and close the file, then restart the Apache service to apply the changes.

systemctl restart apache2

Step 6 – Access Sphinx-Doc

Now, open your web browser and access the Sphinx-Doc using the URL http://your-server-ip. You should see the following page:

Conclusion

Congratulations! You have successfully installed Sphinx-Doc on Ubuntu 20.04 server. You can now use Sphinx-Doc for any documentation project, including one on your dedicated server from Atlantic.Net.

Get A Free To Use Cloud VPS

Free Tier Includes:
G3.2GB Cloud VPS Free to Use for One Year
50 GB of Block Storage Free to Use for One Year
50 GB of Snapshots Free to Use for One Year


Looking for a Hosting Solution?

We Provide Cloud, Dedicated, & Colocation.

  • Seven Global Data Center Locations.
  • Flexible Private, Public, & Hybrid Hosting.
  • 24x7x365 Security, Support, & Monitoring.
Contact Us Now! Med Tech Award FTC
SOC Audit HIPAA Audit HITECH Audit

Recent Posts

Get started with 12 months of free cloud VPS hosting

Free Tier includes:
G3.2GB Cloud VPS Server Free to Use for One Year
50 GB of Block Storage Free to Use for One Year
50 GB of Snapshots Free to Use for One Year


New York, NY

100 Delawanna Ave, Suite 1

Clifton, NJ 07014

United States

San Francisco, CA

2820 Northwestern Pkwy,

Santa Clara, CA 95051

United States

Dallas, TX

2323 Bryan Street,

Dallas, Texas 75201

United States

Ashburn, VA

1807 Michael Faraday Ct,

Reston, VA 20190

United States

Orlando, FL

440 W Kennedy Blvd, Suite 3

Orlando, FL 32810

United States

Toronto, Canada

20 Pullman Ct, Scarborough,

Ontario M1X 1E4

Canada

London, UK

14 Liverpool Road, Slough,

Berkshire SL1 4QZ

United Kingdom

Resources