Fcc software

CONTRIBUTING.md

@@ -1,14 +1,16 @@
 (contributing-lesson)=
 # Contributing
 
-[starterkit-lessons][repo] is an open source project, and we welcome contributions of all kinds:
+[FCC Software][fcc-software] is an open source project, and we welcome
+contributions of all kinds:
 
 * New lessons;
 * Fixes to existing material;
 * Bug reports; and
 * Reviews of proposed changes.
 
-By contributing, you are agreeing that we may redistribute your work under [these licenses][license].
+By contributing, you are agreeing that we may redistribute your work under
+[these licenses][license].
 You also agree to abide by our [contributor code of conduct][conduct].
 
 ## Getting Started
@@ -25,90 +27,81 @@ You also agree to abide by our [contributor code of conduct][conduct].
 5.  If you're looking for things to work on, please see [the list of issues for this repository][issues].
     Comments on issues and reviews of pull requests are equally welcome.
 
+
 ## Building the lessons
 
-### Using `venv` (recommended)
+### Requirements
 
-#### Requirements
-Make sure you have `venv` (virtual environment) in your working directory. It can be created with the following command:
-```
+Make sure you have `venv` (virtual environment) in your working directory. It
+can be created with the following command:
+```shell
 $ python3 -m venv venv
 ```
-Activate it in the shell and install the requirements, which are gathered in a file provided by the repository. 
-```
+Activate it in your shell and install the requirements, which are gathered in a
+file provided by the repository.
+```shell
 $ source venv/bin/activate
 $ pip3 install -r requirements.txt
 ```
 After sourcing, your shell prompt will be augmented by the `(venv)` prefix, e.g.
-```
+```shell
 (venv) mylaptop:~/fcc/fcc-tutorials
 ```
 
-:::{admonition} Building `fcc-tutorials` in FCCSW stack
-:class: solution
+:::{admonition} Building `fcc-tutorials` in FCC Software stack
+:class: callout
 
-In case the Python from FCCSW stack is being used, it is necessary to clear
-`PYTHONPATH` environment variable after sourcing of the stack
-```
+In case the Python from the FCC Software stack is being used, it is necessary to
+clear `PYTHONPATH` environment variable after sourcing of the stack
+```shell
 source /cvmfs/fcc.cern.ch/sw/latest/setup.sh
 unset PYTHONPATH
 ```
 
 Sourcing of the FCCSW stack might be needed in cases when the Python provided by
-the OS is too old, currently this is the case for CentOS 7 (`lxplus`).
+the OS is too old, currently this is the case for CentOS 7 (`lxplus7`).
 :::
 
-#### Building
+### Building
+
 The documentation pages are build by executing
-```
+```shell
 $ sphinx-build -b html . build
 ```
 
-#### Browsing the result
-Open in your browser the file
-```
-$PWD/build/index.html
-```
+### Browsing the result
 
-### Using `starterkit_ci`
+Start a web server to host the generated files from `build` directory
+```shell
+$ cd build
+$ python -m http.server
+```
 
-#### Requirements
+You should be able to see your local version by opening a web-browser and
+navigating to [http://localhost:8000](http://localhost:8000).
 
-To build the lessons locally, install the following:
 
-1. [starterkit-ci](https://pypi.org/project/starterkit-ci/)
+## How to Write Documentation
 
-#### Building
-Build the pages:
+More information about how to write the documentation/tutorials for the FCC
+Software visit
+[](./developing-fcc-software/FccDocPage.md#writing-documentation-for-the-fcc-software).
 
-```shell
-$ starterkit_ci build --allow-warnings
-$ starterkit_ci check --allow-warnings
-```
+## Legal
 
-#### Browsing the result
-Start a web server to host them:
+```{eval-rst}
+.. toctree::
 
-```shell
-$ cd build
-$ python -m http.server 8000
+    CONDUCT.md
+    LICENSE.md
 ```
-You can see your local version by using a web-browser to navigate to `http://localhost:8000` or wherever it says it's serving the book.
 
+
+[fcc-software]: https://fccsw.web.cern.ch/
 [conduct]: CONDUCT.md
-[repo]: https://github.com/HEP-FCC/fcc-tutorials
-[issues]: https://github.com/HEP-FCC/fcc-tutorials/issues
 [license]: LICENSE.md
-[pro-git-chapter]: http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project
+[issues]: https://github.com/HEP-FCC/fcc-tutorials/issues
+[pro-git-chapter]: https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project
 [gh-fork]: https://help.github.com/en/articles/fork-a-repo
 [gh-pull]: https://help.github.com/en/articles/about-pull-requests
 [gh-fork-pull]: https://reflectoring.io/github-fork-and-pull/
-
-
-```{eval-rst}
-.. toctree::
-    :hidden:
-
-    CONDUCT.md
-    LICENSE.md
-```

LICENSE.md

@@ -1,7 +1,9 @@
-# Instructional Material
+# License
+
+## Instructional Material
 
 All instructional material is made available under the [Creative Commons 
-Attribution license][cc-by-human]. The following is a human-readable summary of 
+Attribution license][cc-by-human]. The following is a human-readable summary of
 (and not a substitute for) the [full legal text of the CC BY 4.0 
 license][cc-by-legal].
 
@@ -34,31 +36,15 @@ Notices:
   necessary for your intended use. For example, other rights such as publicity, 
   privacy, or moral rights may limit how you use the material.
 
-# Software
-
-Except where otherwise noted, the example programs and other software provided 
-by Software Carpentry are made available under the [OSI][osi]-approved [MIT 
-license][mit-license].
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of 
-this software and associated documentation files (the "Software"), to deal in 
-the Software without restriction, including without limitation the rights to 
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
-of the Software, and to permit persons to whom the Software is furnished to do 
-so, subject to the following conditions:
+## Software
 
-The above copyright notice and this permission notice shall be included in all 
-copies or substantial portions of the Software.
+Except where otherwise noted, the example programs and other software provided 
+by Software Carpentry are made available under the [OSI][osi]-approved
+[Apache 2.0][apache-license] license.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
-SOFTWARE.
 
 [cc-by-human]: https://creativecommons.org/licenses/by/4.0/
 [cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode
-[mit-license]: https://opensource.org/licenses/mit-license.html
+[apache-license]: https://opensource.org/license/apache-2-0/
 [osi]: https://opensource.org

README.md

@@ -1,20 +1,40 @@
 # The FCC Tutorials
 
-These are the lessons taught during the [FCC Tutorials][tutorial] (the format is heavily inspired by the [LHCb starterkit][lhcb-starterkit]).
-If you'd like to join the next tutorial, visit [the FCCSW website][fccsw-website] to find out when it will happen and how to sign up.
-
-If you'd just like to learn about how to use the FCC software, [read on][first-analysis-steps]!
+These are the lessons taught during the [FCC Software Tutorials][tutorial] (the
+format is heavily inspired by the [LHCb starterkit][lhcb-starterkit]).
+
+List of previous workshop/tutorial events:
+* Computing and software tutorials as part of
+    [Second Annual U.S. Future Circular Collider (FCC) Workshop 2024](https://indico.mit.edu/event/876/)
+    at MIT; 25--27 Mar 2024.
+* Software tutorials as part of
+    [First Annual U.S. Future Circular Collider (FCC) Workshop 2023](https://www.bnl.gov/usfccworkshop/)
+    ([Indico](https://indico.cern.ch/event/1244371/)) at Brookhaven National
+    Laboratory; 24--26 April 2023.
+* [FCC Software Hands-on Tutorial](https://indico.cern.ch/event/1182767/) at
+    CERN; 19--21 October 2022.
+* [Software tutorial](https://indico.cern.ch/event/945608/timetable/?layout=room#147-link-to-software-tutorial)
+    in the context of the Snowmass 2021 studies; 22, 23 and 29 September 2020.
+* [Software tutorial](https://indico.cern.ch/event/838435/timetable/?layout=room#147-link-to-software-tutorial) as part of the FCC Physics week; 15 January 2020.
+* [Software Workshop and hands-on tutorial](https://indico.cern.ch/event/839794/) on 2-3 October 2019; an introduction to many topics.
+
+The next tutorial, will be anounced in
+[FCC-PED-SoftwareAndComputing-Documentation](https://e-groups.cern.ch/e-groups/Egroup.do?egroupName=FCC-PED-SoftwareAndComputing-Documentation) e-group, make sure you
+are subscribed in order to know how to sign up.
+
+If you'd just like to learn about how to use the FCC Software,
+[read on][first-steps]!
 
 [fccsw-website]: https://cern.ch/fccsw
 [tutorial]: https://hep-fcc.github.io/fcc-tutorials
 [lhcb-starterkit]: https://lhcb.github.io/starterkit-lessons/index.html
-[first-analysis-steps]: https://hep-fcc.github.io/fcc-tutorials/software-basics/README.html
+[first-steps]: ./software-basics/README.md#first-steps
 
 
 ```{eval-rst}
 .. toctree::
     :numbered:
-    :maxdepth: 3
+    :maxdepth: 2
     :includehidden:
     :caption: Contents:
 
@@ -31,8 +51,9 @@ If you'd just like to learn about how to use the FCC software, [read on][first-a
     :includehidden:
     :caption: External links:
 
-    FCCSW main page <https://hep-fcc.github.io/FCCSW/>
-    FCCAnalyses reference documentation <https://hep-fcc.github.io/FCCAnalyses/doc/latest/index.html>
+    FCC Software <https://fccsw.web.cern.ch/>
+    FCC-ee Detector Full Sim <https://fcc-ee-detector-full-sim.docs.cern.ch/>
+    FCCAnalyses <https://hep-fcc.github.io/FCCAnalyses/>
     Analysis essentials <https://hsf-training.github.io/analysis-essentials/>
-    FCC software glossary <https://hep-fcc.github.io/glossary>
+    FCC Software glossary <https://hep-fcc.github.io/glossary>
 ```

conf.py

@@ -1,7 +1,7 @@
 # import sphinx_rtd_theme
 
 project = 'FCC Tutorials'
-copyright = '2023, CERN'
+copyright = '2024, CERN'
 html_logo = '_static/img/fcc-logo-light.png'
 html_favicon = '_static/img/favicon.ico'
 html_theme = 'sphinx_rtd_theme'
@@ -19,7 +19,7 @@
     'display_github': True,
     'github_user': 'HEP-FCC',
     'github_repo': 'fcc-tutorials',
-    'github_version': 'master/',
+    'github_version': 'main/',
 }
 
 extensions = [

developing-fcc-software/FccDocPage.md

@@ -1,82 +1,34 @@
-# Writing documentation for the FCC software
+# Writing documentation for the FCC Software
 
 
 ## Where to put documentation
 
-- API documentation of classes and functions is done with Doxygen notation in the source code.
-- Slightly higher level documentation on usage of a piece of software is usually put directly in the corresponding repository.
-- Long-form documentations  that introduce users to a piece of software belong in [fcc-tutorials](https://hep-fcc.github.io/fcc-tutorials/).
+- API documentation of classes and functions should be done using Doxygen
+    notation directly in the source code.
+- Slightly higher level documentation on usage of a piece of software is
+    usually put directly in the corresponding repository.
+- Long-form documentations that introduces users to a piece of software belongs
+    into [fcc-tutorials](https://hep-fcc.github.io/fcc-tutorials/).
 
 :::{admonition} Where to put documentation
 :class: callout
 
-It is sometimes difficult to decide between the last two. In those cases either will be great.
+It is sometimes difficult to decide between the last two. In those cases either
+will be great.
 :::
 
 
-## When and how is the documentation page updated?
+## How to write Mardown
 
-There are both a main website (<https://cern.ch/fccsw>) and a readthedocs-style page for the tutorials (<https://hep-fcc.github.io/fcc-tutorials/>).
-
-Both consists of a static website based on `github-pages`. The  main website points to EOS (`/eos/project/f/fccsw-web/www`), from where it is redirected to the github-pages site of FCCSW. Only members
-of the corresponding e-group have write access. All markdown and configuration files are stored in the [`gh-pages`](https://github.com/HEP-FCC/FCCSW/tree/gh-pages) branch of the
-FCCSW Github repository. All dependencies (jquery, bootstrap-sass) are included in the mentioned repository and any change should be automatically deployed to:
-
-[http://hep-fcc.github.io/FCCSW/](http://hep-fcc.github.io/FCCSW/)
-
-
-## Structure of the content of the main page
-
-Folders can be added to aggregate markdown files by category:
-
-- `computing`: FCC Computing Resources
-- `presentations`: Selection of Publications and Presentations relating to FCC Software
-...
-
-The rest of folders and files are mainly configuration files to generate the website itself with [Jekyll](https://jekyllrb.com/):
-
-- `_data`: Contains `permalinks.yaml` YAML file with the links shown on the website
-- `_includes`: HTML files to define the structure of the website (header, footer, ...)
-- `_layouts`: HTML Structure for those part that are commonly used (posts, sites, title headers, ...)
-- `css`: Define the style of the website
-- `geo`: Geometry visualization
-- `node_modules`: Contains Javascript installed dependencies
-- `Gemfile`: Define Ruby dependencies
-- `package.json`: Define Javascript dependencies
-- `_config`: General configuration file with metadata used by Jekyll
-
-
-## Running website generation locally
-
-**This is meant for testing not to override the generated website!**
-
-Modify the content and serve the page with:
-
-```bash
-jekyll serve --baseurl=
-```
-
-Now you should be able to see the website at `localhost:4000`.
-
-
-### About jekyll
-
-We are using jekyll to build our website. If you are interested in extending the website have a look in
-the [repository](https://github.com/HEP-FCC/FCCSW/tree/gh-pages). Documentation of jekyll may be found
-[elsewhere](https://jekyllrb.com/). In case of questions contact the fcc-experiments-sw-dev mailing list.
-
-
-## For website admins
-
-Administrators controlling access to the webspace need to be members of the e-group `cernbox-project-fccsw-web-admins`.
-
-If you want to have write-access you need to request membership in
-`cernbox-project-fccsw-web-writers`. If you are the main responsible for these activities, you should own the service account `fccsweos` that has admin rights for both the physics data EOS space and the web EOS space.
+This tutorial website is generated with [Sphinx](https://www.sphinx-doc.org/)
+machinery using [Read the Docs](https://readthedocs.org/) theme. Specific
+parser of Mardown we use is [MyST](https://myst-parser.readthedocs.io).
 
 
 ## Custom Admonitions
 
-The `fcc-tutorial` makes use of custom admonition classes:
+The `fcc-tutorial` makes use of the following custom admonition classes
+inherited from [LHCb Starterkit](https://lhcb.github.io/starterkit-lessons/):
 
 * prereq
 * callout
@@ -120,3 +72,21 @@ Text of a collapsable admonition.
 
 Text of a collapsable admonition.
 :::
+
+
+## When and how is the tutorials page updated?
+
+This tutorials page is hosted at <https://hep-fcc.github.io/fcc-tutorials/> and
+the edits are managed using Github pull requests. Once the pull request is
+merged the change to the tutorials page will happen within few minutes.
+
+
+## For website admins
+
+Administrators controlling access to the webspace need to be members of the
+`cernbox-project-fccsw-web-admins` e-group.
+
+If you want to have write-access you need to request membership in
+`cernbox-project-fccsw-web-writers`. If you are the main responsible for these
+activities, you should own the service account `fccsweos` that has admin rights
+for both the physics data EOS space and the web EOS space.