From 6d12de6ff6a910e64e23e83472469c38965812b7 Mon Sep 17 00:00:00 2001 From: Fabio Hernandez Date: Fri, 18 May 2018 16:51:37 +0200 Subject: [PATCH] Improve developer documentation --- devdocs/README.md | 30 +++++ .../workflow.png | Bin howToBuildDoc.md | 111 ------------------ 3 files changed, 30 insertions(+), 111 deletions(-) create mode 100644 devdocs/README.md rename lsst-france-sw-diagram.png => devdocs/workflow.png (100%) delete mode 100644 howToBuildDoc.md diff --git a/devdocs/README.md b/devdocs/README.md new file mode 100644 index 0000000..70ddbb1 --- /dev/null +++ b/devdocs/README.md @@ -0,0 +1,30 @@ +# Developer documentation + +This document contain instructions on how to trigger the continuous integration machinery for building the documentation of +site [https://sw.lsst.eu](https://sw.lsst.eu). + +The sources of the documentation are located in the `docs` directory of this repository. To build them do: + +```bash +git clone git@gitlab.in2p3.fr:brigaud/sw-lsst-eu.git +cd sw-lsst-eu +git checkout -b +``` + +The last step, i.e. creating your own branch is very important. You can now modify the contents of your local copy of the files in the `docs` directory and commit your changes. Then do: + +```bash +git push +``` + +This push operation will trigger the CI infrastructure. You can preview the modified version of the documentation at the address: `https://sw.lsst.eu/preview/`. + +Once you are happy with your modifications and want to push them in production make a merge request via the command line or by visiting: + +``` +https://gitlab.in2p3.fr/brigaud/sw-lsst-eu/merge_requests/new?merge_request%5Bsource_branch%5D= +``` + +You can have an overview of the process in the diagram below: + +![Workflow](workflow.png "Workflow") \ No newline at end of file diff --git a/lsst-france-sw-diagram.png b/devdocs/workflow.png similarity index 100% rename from lsst-france-sw-diagram.png rename to devdocs/workflow.png diff --git a/howToBuildDoc.md b/howToBuildDoc.md deleted file mode 100644 index 7cfd6c0..0000000 --- a/howToBuildDoc.md +++ /dev/null @@ -1,111 +0,0 @@ -LSST FRANCE DOCUMENTATION -========================= - -
- -Introduction ----------- -*** - -This repository contains LSST documentation sources (reStructuredText file format). -Updating content on this repository automatically generates and publishes online documentation. - -
- -Goals ----------- -*** - -- Manage collaboration between LSST documention's authors -- Generate & Publish LSST Documentation - -
- -Workflow ----------- -*** - -Each author works on his own branch and can see a preview at every push. -Once the author is satisfied, he can merge his branch with the master branch. -The merge in master generates and publishes the official version. -This repository only contains source documentation (.rst files). -Authors must write documentation respecting this format. -More info on the reStructuredText (rst) file format: https://en.wikipedia.org/wiki/ReStructuredText - -![LSST France Software Doc Diagram](lsst-france-sw-diagram.png "LSST France Software Doc Diagram") - -### master branch is the official doc that is pushed online at http://sw.lsst.eu/. -### Documentation generation and uploading is fully automated. - -
- -Instructions ----------- -*** - -**Step1**: clone the repo and create your own branch from master - -```bash -git clone git@gitlab.in2p3.fr:brigaud/sw-lsst-eu.git -cd sw-lsst-eu -git checkout -b -``` - -**Step2**: create/modify your doc in your branch then push it - -```bash -git add --all -git commit -m "your changes comments" -git push -``` -... wait about a minute and check it out at http://sw.lsst.eu/preview/\. - -
- -> **Note:** - -> - Each push on your branch will generate a documentation at http://sw.lsst.eu/preview/\ -> - Useful for preview. - -
- -**Step3**: send a merge request to master branch to put documentation in production -

-https://gitlab.in2p3.fr/brigaud/sw-lsst-eu/merge_requests/new?merge_request%5Bsource_branch%5D=\ -

-An administrator will check your version, fix conflicts and finally merge your branch into master branch.
-This merge will automatically trigger the build process and update the official documentation at http://sw.lsst.eu/. - -
- -> **Note:** - -> - Each merge on master branch will generate a documentation at http://sw.lsst.eu - -
- -> **Important**: - -> - Each time master builds a new official doc, preview folder (i.e http://sw.lsst.eu/preview) is deleted - -
- -Recommandations --------------------- -*** - -All the documentation resides in the "docs" folder. -You can create or delete files and folders in order to create your documentation. -Be sure to update the index.rst file in case you add or delete documentation files or folders in order to access it from the sidebar menu on the website. - -
- -> **Note:** - -> - As a community project, it is recommended to work only on parts you've been assigned -> - Keep as much as possible the original tree structure -> - Keep as much as possible your branch up-to-date with respect to master branch (i.e git rebase master ) - -
- -Happy doc!