.. _sphinx-doc: .. _getting-started: =============================== How to use Sphinx Documentation =============================== The method below allows you to write and preview the doc easily thanks to **VSCode** and the `Dev Container `_ technology. .. important:: We do not provide support for other installation methods. A ``requirements.txt`` file is available at the root of the documentation one can consult the content of the ``.devcontainer`` folder to install the required programs and tools to build the documentation on its own. Requirements ------------ * `Visual Studio Code `_ * `Docker engine `_ * `Dev Containers extension `_ Quick start ----------- Clone the repository and open the folder in VSCode. .. prompt:: bash git clone https://gitlab.hevs.ch/SPL/spl-docs.git cd spl-docs code . The ``.devcontainer`` folder within the root of the documentation will be detected by VSCode and this latter will ask you to open the folder in a container. Confirm the action. If the dialog doesn't show up, open the command palette (``Ctrl+Shift+P`` or ``F1``) and search for ``Dev Containers: Open Folder in Container...``. Once the container is built, you are ready to read and write some doc. A live preview is available at http://localhost:1950. This live preview update whenever a change in the source folder is detected. Install new package ------------------- If you write a documentation and find an useful extension or package to be added, use the standard ``pip install`` command. Note that this will install the package only on your local devcontainer. As long as you don't rebuild the container, you don't have to reinstall the package again. To make the installation of the package permanent, don't forget to add this latter in the ``requirements.txt`` file. Available commands ------------------ This documentation comes with a ``justfile`` (Makefile replacement). Use ``just -l`` to see the availabe recipes: .. code-block:: bash $ just -l Available recipes: clean # Delete build folder(s) html # Build HTML static site livehtml # Build and serve static HTML pages publichtml # Build and copy HTML in public folder (gitlab deployment) Commit your changes ------------------- Before performing a commit the following steps are required: * Verify the build of the documentation locally: .. prompt:: bash just clean && just html * Solve important build ``Warnings`` and ``Errors`` (if any) in the output. * Commit and push your changes Continuous Integration(CI) ========================== The :download:`.gitlab-ci.yml ` will run on each ``master`` commit and create a ``public/`` folder which will be used by gitlab pages and displayed as static html pages. :tag:`Sphinx` :tag:`Installation` :tag:`How to`