Making evolutions to existing website

Understanding source files hierarchy

The high level structure of sphinx project is the following :

~home
├── sphinx
    ├── docs
        ├── build
        ├── source
        make.bat
        Makefile

The source *.rst pages should be created in the source directory. Once the source pages are finalised, we can run the make.bat script that generates *.html webpages in the build directory.

The final webpages are structured using the initial directory hierarchy that is defined by the source directory for *.rst pages. In our case the stuctured of the source directory is as follows :

~home
├── sphinx
    ├── docs
        ├── build
        ├── source
            cong.py
            logo.png
            index.rst
            theme1_overview.rst
            theme2_overview.rst
            theme3_overview.rst
            ├── _static/img
            ├── _templates
            ├── theme1
                ├── theme1_section1.rst
                ├── theme1_section2.rst
                ├── theme1_section3.rst
                ├── theme1_section1_subsection1.rst
                ├── theme1_section1_subsection2.rst
                ├── theme1_section1_subsection3.rst
            ├── theme2
            ├── theme3

Adding new content

When adding new content, follow the next steps :

1. If it’s a new theme, first create the new_theme.rst file at the same level than the index.rst with the content of the new theme. Then edit the index.rst and add the name of the link and the *.rst page that you crated previously.

For example in the index.rst file add the following in the .. toctree:: section :

Introduction <new_theme.rst>

2. If it’s a new section within an existing theme, first create the new_section.rst file under the existing_theme directory with the content of the new section. Then edit the equivalent of existing_theme.rst file at the same level as index.rst to add the name of the link and the path to the *.rst page that was created previously.

For example in the existing_theme_overview.rst file add the following in the .. toctree:: section :

New section </existing_theme/new_section.rst>

3. If it’s a new subsection within an existing section, first create the new_subsection.rst file under the existing_theme directory with the content of the new subsection. Then edit the equivalent of /theme1/existing_section.rst file to add the name of the link and the path to the *.rst page that was created previously.

For example in the /theme1/existing_section.rst file add the following in the .. toctree:: section :

New subsection </theme1/new_subsection.rst>

4. If it’s a new content within an existing subsection, you don’t need to create a new *.rst. Simply edit the equivalent of /theme1/existing_subsection.rst file and add the necessary content using *.rst conventions.

For example in the /theme1/existing_subsection.rst file add the following content:

New content to existing subsection with rst conventions

Generating new html files after adding content

Once you have finished adding necessary additional content, you can execute the build of the new webpages by executing the following command

usr1@server:$ cd ~/sphinx
usr1@server:~/sphinx$ source .venv/bin/activate  #this instruction will activate the virtual environement
(.venv) usr1@server:~/sphinx$ sphinx-build -M html docs/source/ docs/build/ #this instruction will generate *.html files in the docs/build/ directory from the source *.rst files that are in docs/source/

The following line should be displayed at the end of the script execution The HTML pages are in docs/build/html. To deactivate the python virtual environment execute the following :

(.venv) usr1@server:~/sphinx$ deactivate

Deploying new html files to the webserver

Once the new *.html files are generated in the docs/build/ directory, copy the content of the directory into /var/www/directory_name to deploy changes on the webserver.

usr1@server:$ cd ~/sphinx
usr1@server:~/sphinx$ cd docs
usr1@server:~/sphinx/docs$ cp -r build/html /var/www/{name of the directory}/

The previous command should copy all the content of the ~/sphinx/docs/build/html to the directory /var/www/{name of the directory}/html

Refresh your webpage to visualise the changes.