###################################################
Making evolutions to existing website
###################################################


Understanding source files hierarchy
====================================================================

The high level structure of sphinx project is the following : 

.. code-block:: bash

    ~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 :

.. code-block:: bash

    ~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 :

.. code-block:: bash

    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 :

.. code-block:: bash

    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 :

.. code-block:: bash

    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:

.. code-block:: bash

    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

.. code-block:: bash

    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 :


.. code-block:: bash

    (.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.


.. code-block:: bash

    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.