From b16c68134ebcdee3df30329cdaaf08ae62fb0b56 Mon Sep 17 00:00:00 2001 From: Cecilia Date: Mon, 9 Sep 2024 17:56:28 +0200 Subject: [PATCH 1/2] Adding Sphinx Documentation --- .gitignore | 3 +- docs/source/git.rst | 65 -------------------------------------- docs/source/index.rst | 6 ++++ docs/source/sphinx.rst | 72 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 80 insertions(+), 66 deletions(-) create mode 100644 docs/source/sphinx.rst diff --git a/.gitignore b/.gitignore index e864704..9d84ee1 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -**/build/ \ No newline at end of file +**/build/ +**.DS_Store diff --git a/docs/source/git.rst b/docs/source/git.rst index f53867a..2a0b527 100644 --- a/docs/source/git.rst +++ b/docs/source/git.rst @@ -102,68 +102,3 @@ If you no longer need the branch locally, you can delete it: .. code:: bash git branch -d update_readme - - -Modifying the HTML Webpage ---------------------------- - -1. Compile the HTML Webpage Locally -____________________________________ - -To compile the HTML files locally, navigate to the parent directory of your project and run: - -.. code-block:: bash - - make html - -This command will generate the HTML files for your webpage. - -**Troubleshooting:** - -- If the ``make html`` command fails, you might need to install the necessary dependencies first. You can do this by running: - - .. code-block:: bash - - pip install -r requirements.txt - -2. View the Compiled HTML -__________________________ - -Once the compilation is successful, you can view the HTML files by navigating to the ``docs/build/html`` directory. Open the files in this folder with your preferred web browser to see your webpage. - -3. Modify the Documentation -____________________________ - -**Important:** - -- **Never modify files directly in the** ``html`` **folder.** -- Always make changes in the ``docs/source`` folder, which contains the source files used to generate the HTML. - -**Steps for Modifying Content:** - -1. **Create a New** ``.rst`` **File:** - - If you need to add new content, you can create a new ``.rst`` file in the ``docs/source`` directory. Use an existing file, such as ``oar.rst``, as a template for the new file. - - - **Formatting Tips:** For guidance on formatting ``.rst`` files, refer to `appropriate documentation `_. - - -2. **Update the** ``index.rst`` **File:** - - After adding or modifying ``.rst`` files, update the ``index.rst`` file to include your new content in the table of contents or navigation structure. - -4. Re-compile the HTML Webpage -_______________________________ - -Once you've made your changes, recompile the HTML files by running ``make html`` again from the parent directory (``docs``), where the ``make.bat`` file is located: - -.. code-block:: bash - - make html - -This will regenerate the HTML files with your latest modifications. - -5. Commit and Push Changes -__________________________ - -After confirming your changes are reflected in the compiled HTML, it's time to commit and push your changes to the repository. For detailed instructions on how to commit and push changes, see see `Getting Started with Git and GitHub <#getting-started-with-git-and-github>`_. diff --git a/docs/source/index.rst b/docs/source/index.rst index 8626680..e2845fe 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,3 +15,9 @@ start a discussion on |GitHub_discussion| oar git + +.. toctree:: + :maxdepth: 2 + :caption: Contributors: + + sphinx diff --git a/docs/source/sphinx.rst b/docs/source/sphinx.rst new file mode 100644 index 0000000..cafeffc --- /dev/null +++ b/docs/source/sphinx.rst @@ -0,0 +1,72 @@ +Sphinx tips +=========== + +Contributing to this Documentation +---------------------------------- + +1. Compile the HTML Webpage Locally +____________________________________ + +To compile the HTML files locally, navigate to the parent directory of your project and run: + +.. code-block:: bash + + make html + +This command will generate the HTML files for your webpage. + +**Troubleshooting:** + +- If the ``make html`` command fails, you might need to install the necessary dependencies first. You can do this by running: + + .. code-block:: bash + + pip install -r requirements.txt + +2. View the Compiled HTML +__________________________ + +Once the compilation is successful, you can view the HTML files by navigating to the ``docs/build/html`` directory. Open the files in this folder with your preferred web browser to see your webpage. + +3. Modify the Documentation +____________________________ + +**Important:** + +- **Never modify files directly in the** ``html`` **folder.** +- Always make changes in the ``docs/source`` folder, which contains the source files used to generate the HTML. + +**Steps for Modifying Content:** + +1. **Create a New** ``.rst`` **File:** + + If you need to add new content, you can create a new ``.rst`` file in the ``docs/source`` directory. Use an existing file, such as ``oar.rst``, as a template for the new file. + + - **Formatting Tips:** For guidance on formatting ``.rst`` files, refer to `appropriate documentation `_. + + +2. **Update the** ``index.rst`` **File:** + + After adding or modifying ``.rst`` files, update the ``index.rst`` file to include your new content in the table of contents or navigation structure. + +4. Re-compile the HTML Webpage +_______________________________ + +Once you've made your changes, first delete previous files to avoid conflict: + +.. code-block:: bash + + make clean + +Second recompile the HTML files by running ``make html`` again from the parent directory (``docs``), where the ``make.bat`` file is located: + +.. code-block:: bash + + make html + +This will regenerate the HTML files with your latest modifications. + +5. Commit and Push Changes +__________________________ + +After confirming your changes are reflected in the compiled HTML, it's time to commit and push your changes to the repository. For detailed instructions on how to commit and push changes, see `Getting Started with Git and GitHub <#git-tips>`_. From b40e99d55e1a74541e8b7147784d0a3a088cd56b Mon Sep 17 00:00:00 2001 From: Cecilia Date: Mon, 9 Sep 2024 18:01:51 +0200 Subject: [PATCH 2/2] We updated the Theme --- docs/source/conf.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 3e07d58..5fc486b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -13,19 +13,16 @@ # These are options specifically for the Wagtail Theme. html_theme_options = dict( project_name = "PSM tips", + github_url = "https://github.com/psm-compute/psm-compute.github.io/tree/main/docs/source/" # logo_alt = "Wagtail", # logo_height = 59, # logo_url = "/", # logo_width = 45, ) -html_theme_options = dict( - github_url = "https://github.com/psm-compute/psm-compute.github.io/tree/main/docs" -) - html_theme = 'sphinx_wagtail_theme' html_static_path = ['_static'] html_title = "PSM tips and trics page" html_show_copyright = False -html_show_sphinx = False \ No newline at end of file +html_show_sphinx = False