Skip to content

Commit

Permalink
Updating Contribution instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@kjvbrt
kjvbrt committed Jul 30, 2024
1 parent 265eff2 commit ead360d
Show file tree
Hide file tree
Showing 6 changed files with 106 additions and 144 deletions.
91 changes: 42 additions & 49 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
[issues]: https://github.com/HEP-FCC/fcc-tutorials/issues
[pro-git-chapter]: http://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
```
32 changes: 9 additions & 23 deletions LICENSE.md
View file
Original file line number Diff line number Diff line change
@@ -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].

Expand Down Expand Up @@ -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
25 changes: 19 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,33 @@
# 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.
These are the lessons taught during the [FCC Software Tutorials][tutorial] (the
format is heavily inspired by the [LHCb starterkit][lhcb-starterkit]).

If you'd just like to learn about how to use the FCC software, [read on][first-analysis-steps]!
List of previous workshop/tutorial events:
* [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:
Expand All @@ -34,5 +47,5 @@ If you'd just like to learn about how to use the FCC software, [read on][first-a
FCCSW main page <https://hep-fcc.github.io/FCCSW/>
FCCAnalyses reference documentation <https://hep-fcc.github.io/FCCAnalyses/doc/latest/index.html>
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>
```
4 changes: 2 additions & 2 deletions conf.py
View file
Original file line number Diff line number Diff line change
@@ -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'
Expand All @@ -19,7 +19,7 @@
'display_github': True,
'github_user': 'HEP-FCC',
'github_repo': 'fcc-tutorials',
'github_version': 'master/',
'github_version': 'main/',
}

extensions = [
Expand Down
96 changes: 33 additions & 63 deletions developing-fcc-software/FccDocPage.md
View file
Original file line number Diff line number Diff line change
@@ -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/). 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
Expand Down Expand Up @@ -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.
2 changes: 1 addition & 1 deletion software-basics/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# First Steps
# First Steps

This is the FCC Tutorials, a series of lessons for getting physicists working confidently with FCC data and software.
The lessons are best approached one after the other, as most lessons build on the knowledge gained from the previous ones.
Expand Down

0 comments on commit ead360d

Please sign in to comment.