Commit 77f77e41 authored by Alexander Martinez's avatar Alexander Martinez
Browse files

Readme versión OLS y mkdocs documentación a herramientas

parent 65e14202
<!--
[![pipeline status](https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs/badges/master/pipeline.svg)](https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs/-/commits/master)
-->
<div align="center">
#Bienvenidos!
<img alt="ReDoc logo" src="docs/images/logo-laconga-nt.png" width="150px" />
# URL de los cursos de LA-CoNGA physics
**LA-CoNGA physics (Latin American alliance for Capacity buildNG in Advanced physics)**
[https://laconga.redclara.net/courses/index.html](https://laconga.redclara.net/courses/index.html)
---
# Utilizando MkDocs en tu propio computador
## Requirement:
### MkDocs:
### Get it in https://www.mkdocs.org/
<!--
[![pipeline status](https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs/badges/master/pipeline.svg)](https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs/-/commits/master)
[![coverage report](https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs/badges/master/coverage.svg)](https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs/-/commits/master)
-->
</div>
* Follow the instructions below in section **Building your project documentation**
<!--
**_This README.md file in also available in Spanish ([README-Spanish]())_**
-->
### **For Latex-kind and Maths**
First and foremost, Welcome! 🎉 Te damos la bienvenida 🎊 :partying_face:!
* ```python-markdown-math```
Thank you for visiting LA-CoNGA physics Courses21B repository.
Get it (install using ```pip```) as mentioned in: https://github.com/mitya57/python-markdown-math
Jump straight to one of the sections below, or just scroll down to find out more.
---
Table of contents:
**Once you get those installed**:
- [About LA-CoNGA physics](#About-the-project)
- [What are we doing?](#What-are-we-doing?)
- [Why are we doing it?](#Why-are-we-doing-it?)
- [Courses 2021B](#courses-2021b)
- [The team](#the-team)
- [Do you want to contribute?](#do-you-want-to-contribute?)
- [Get in touch](#get-in-touch)
- [Citing _LA-CoNGA physics_](#citing-LA-CoNGA-physics)
- [Acknowledgment](#acknowledgment)
- [Contributors ✨](#contributors-)
## About the project
You can follow this instruction:
``` shell
git clone https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs.git
cd tutorial-mkdocs
mkdocs serve
```
### What are we doing?
To put it in App, you need to generate HTML by:
```
mkdocs build
```
_LA-CoNGA Physics_ is an [Erasmus+ Capacity Building](https://ec.europa.eu/programmes/erasmus-plus/opportunities/organisations/innovation-good-practices/capacity-building-higher-education_en) project, an European-Latinamerican network which aims to support the modernization of the university infrastructure and the pedagogical offer in advanced physics in four Latin American countries: Colombia, Ecuador, Peru and Venezuela. This virtual teaching and research network is composed of 3 partner universities in Europe and 8 in Latin America, high-level scientific partners (CEA, CERN, CNRS, DESY, ICTP), and several academic and industrial partners (including redCLARA, CAEN, among others). The project is co-funded by the Education, Audiovisual and Culture Executive Agency (EACEA) of the European Commission. _LA-CoNGA physics_ started officially in January 2020 and has an initial funding for 3 years.
---
# Building your project documentation
In practice _LA-CoNGA physics_ has created a set of postgraduate courses in Advanced Physics (high energy physics and complex systems) that are common and inter-institutional, supported by the installation of interconnected instrumentation laboratories and an open e-learning platform. This program is inserted as a specialization in the Physics masters of the 8 Latinamerican partners in Colombia, Ecuador, Peru and Venezuela. It is based on three pillars: courses in physics theory/phenomenology, data science and instrumentation.
[**MkDocs**](https://www.mkdocs.org) is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation.
Documentation source files are written in **Markdown**, and configured with a single YAML configuration file.
More information can be found at: https://laconga.redclara.net
## **Mkdocs installation**
### Why are we doing it?
* **Prerequisite: Python and Pip**
STEM master programs in most of Latinamerica focus on the scientific theoretical aspects, with little formal training in data science and instrumentation so needed in today’s world inside and outside academia. In this sense _LA-CoNGA physics_ ’ pedagogical offer is a first of its kind in the region. In addition, working in a network configuration allows to combine the technical and personpower resources from the institutions to create such a pedagogical offer. Together we are stronger.
In order to manually install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have these already installed from the command line:
We are guided by the principles of open science and open education. The development of robust, open research in our partner institutions could have global benefits and global collaborations like _LA-CoNGA physics_ would increase their access to resources that might currently be off limits. We want to:
* Promote open science values such as reproducibility, transparency and openness in the partner universities
* Create a dynamic and international community trained in open science principles and advocate for them
**On Windows:**
### LA-CoNGA Physics Courses 2021B
```
C:\Users\User>python --version
Python 3.5.4
C:\Users\User>pip --version
pip 9.0.1
```
<!--
Pendiente ...
-->
**On MacOS or Linux**
#### Useful Links
```
$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2
```
- [LA-CoNGA Physics Courses Web Page](https://laconga.redclara.net/courses/)
* **Installing Python**
Install [Python](https://www.python.org/) by downloading an installer appropriate for your system from [python.org](https://www.python.org/downloads/) and running it.
## LA-CoNGA physics mission and vision
**Note:**
If you are installing Python on Windows, be sure to check the box to have Python added to your PATH if the installer offers such an option (it's normally off by default).
_LA-CoNGA physics_ mission is the creation of a Latin-American-European Virtual Research and Learning Community in the field of Advanced Physics to promote the values of collaboration, open education and open research in institutes from Colombia, Ecuador, Peru and Venezuela. We will train a new generation of scientists in Latin-America through a one-year master level specialization program that focuses on three pillars of knowledge: theoretical physics, instrumentation in experimental design and data science. We will build a diverse collaborative network that allows the students to access tools, equipment, and know-how that would otherwise not be available.
![path](https://www.mkdocs.org/img/win-py-install.png)
## The team
* **Installing Pip**
[_LA-CoNGA physics_ network](https://laconga.redclara.net/our-partners/) is composed of 11 universities, 9 research institutions and 3 industrial partners in advanced physics:
If you're using a recent version of Python, the Python package manager, pip, is most likely installed by default. However, you may need to upgrade pip to the lasted version:
`pip install --upgrade pip`
### Institutions
If you need to install pip for the first time, download get-pip.py. Then run the following command to install it:
`python get-pip.py`
- Universidad Antonio Nariño (UAN) :colombia:
- Universidad Industrial De Santander (UIS) :colombia:
- Universidad San Francisco De Quito (USFQ) :ecuador:
- Universidad De Investigación De Tecnología Experimental Yachay (YACHAY TECH) :ecuador:
- Universidad Nacional De Ingeniería (UNI) :peru:
- Universidad Nacional Mayor De San Marcos (UNMSM) :peru:
- Universidad Central De Venezuela (UCV) :venezuela:
- Universidad Simón Bolívar (USB) :venezuela:
- Université De Paris :fr:
- University Paul Sabatier, Toulouse Iii (UPS) :fr:
- Technische Universitaet Dresden (TUD) :de:
* **Installing MkDocs**
### Research Institutions & Industrial Partners
- Centre National De La Recherche Scientifique (CNRS) :fr:
- European Organization for Nuclear Research (CERN) :switzerland:
- Deutsches Elektronen-Synchrotron (DESY) :de:
- Abdus Salam International Centre for Theoretical Physics (ICTP) :it:
- Institute of research into the fundamental laws of the Universe (IRFU) :fr:
- RedCLARA
- Centro Virtual de Altos Estudios de Altas Energias (CEVALE2) :venezuela:
- Asociación Colombiana para el Avance de la Ciencia (AvanCiencia) :colombia:
- New York Academy of Sciences :us:
- CAEN :it:
- DBAccess
- Frontier X Analytics :colombia:
- Alan Turing Institute :uk:
Install the `mkdocs` package using pip:
```
pip install mkdocs
```
We have a wonderful team, please go to the bottom of the page in the section [Contributors ✨](#contributors-) to meet them.
You should now have the `mkdocs` command installed on your system. Run `mkdocs--version` to check whether successfully installed.
## Do you want to contribute?
**On Windows:**
```
C:\Users\User>mkdocs --version
mkdocs, version 1.0.4
```
**On MacOS or Linux**
```
$ mkdocs --version
mkdocs, version 0.15.3
```
## **Getting started to edit**
:construction: This project is a work in progress and we are always looking for motivated people to help us build something that is useful for our students :construction:
* Clone this documentation to your device by git
We need experts (researchers and teachers) in the Advanced physics for curricula design, in interconnected instrumentation, in data management (particularly ensuring the highest quality data protection plans are in place), in communication, in fundraising, app development, user experience design and documentation.
Clone with https:
```
git clone git clone https://github.com/LA-CoNGA-MiLab-RedClara/tutorial-mkdocs.git
If you think you can help in any of the areas listed above (and we bet you can) or in any of the many areas that we haven't yet thought of (and here we're sure you can) then please contact our project manager by email at [contacto@laconga.redclara.net](mailto:contacto@laconga.redclara.net)
cd tutorial-mkdocs
```
You can follow also the project in our social networks:
In your `docs` folder, you will see a configuration file named `mkdocs.yml`, and a folder named `docs` that will contain your documentation source files.
- [@lacongaphysics](https://twitter.com/lacongaphysics) on Twitter
- [@lacongaphysics](https://www.facebook.com/lacongaphysics) on Facebook
- [@lacongaphysics](https://www.instagram.com/lacongaphysics/) on Instagram
- [Youtube Channel](https://www.youtube.com/channel/UCcXSolYkpCW_iYxHrnSJw0w)
![folder1](https://github.com/veritasalice/MarkdownPhotos/blob/master/folder1.png?raw=true)
Please note that it's very important to us that we maintain a positive, open, safe and supportive learning environment for everyone who wants to participate. When you join us we ask that you follow our [code of conduct](CODE_OF_CONDUCT.md) in all interactions both on and offline.
Right now the `docs` folder just contains all the documentation pages, such as `index.md`, `datasets.md` and the folders where the pages are saved.
## Citing _LA-CoNGA Physics_ <!--es necesario???-->
<!--
For now we do not have anything. To be added later.
+ Define granularity
+ Propouse:
- publish a package for every module.
-->
![folder2](https://github.com/veritasalice/MarkdownPhotos/blob/master/folder2.png?raw=true)
We really appreciate any references that you make to LA-CoNGA Physics project and we hope it is useful. If you have any questions please [get in touch.](#Get-in-touch)
## Thank you
MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` configuration file, and then start the server by running the `mkdocs serve` command:
```
C:\Users\User\tutorial-mkdocs>mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 190705 15:13:53 server:296] Serving on http://127.0.0.1:8000
[I 190705 15:13:53 handlers:62] Start watching changes
[I 190705 15:13:53 handlers:64] Start detecting changes
```
Thank you so much (Gracias :smiling_face_with_three_hearts:!) for visiting the project and we do hope that you'll join us on this amazing journey to .
Open up `http://127.0.0.1:8000/` in your browser, and you'll see the pages you cloned being displayed:
## Acknowledgment
![pic3](https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs/blob/master/docs/images/la-conga.png?raw=true)
We are grateful to the Ecuadorian National Research and Education Network _CEDIA_ and to _RedCLARA_ for providing us with the technological capabilities for these services.
Use the editor you like to edit the files in `docs` and your changes will be displayed when saving them.
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable
<table>
<tr>
<td align="center"><a href="https://twitter.com/mxrtinez"><img src="https://avatars.githubusercontent.com/u/5553457?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Alexander Martínez Méndez</b></sub></a><br /><a href="https://github.com/LA-CoNGA/OLS/commits?author=mxrtinez" title="Code">💻</a> <a href="#content-mxrtinez" title="Content">🖋</a> <a href="https://github.com/LA-CoNGA/OLS/commits?author=mxrtinez" title="Documentation">📖</a> <a href="#ideas-mxrtinez" title="Ideas, Planning, & Feedback">🤔</a> <a href="#maintenance-mxrtinez" title="Maintenance">🚧</a> <a href="#platform-mxrtinez" title="Packaging/porting to new platform">📦</a></td>
<td align="center"><a href="https://github.com/camachoreina"><img src="https://avatars.githubusercontent.com/u/12454015?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Reina Camacho Toro</b></sub></a><br /><a href="https://github.com/LA-CoNGA/OLS/commits?author=camachoreina" title="Code">💻</a> <a href="#content-camachoreina" title="Content">🖋</a> <a href="#data-camachoreina" title="Data">🔣</a> <a href="#eventOrganizing-camachoreina" title="Event Organizing">📋</a> <a href="#fundingFinding-camachoreina" title="Funding Finding">🔍</a> <a href="https://github.com/LA-CoNGA/OLS/commits?author=camachoreina" title="Documentation">📖</a> <a href="#ideas-camachoreina" title="Ideas, Planning, & Feedback">🤔</a> <a href="#mentoring-camachoreina" title="Mentoring">🧑‍🏫</a> <a href="#projectManagement-camachoreina" title="Project Management">📆</a> <a href="#translation-camachoreina" title="Translation">🌍</a> <a href="#talk-camachoreina" title="Talks">📢</a> <a href="#video-camachoreina" title="Videos">📹</a></td>
</tr>
</table>
## **Using the Git to commit your changes**
-->
By far, the most widely used modern version control system in the world today is Git.
In Git, every developer's working copy of the code is also a repository that can contain the full history of all changes.
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
**Prerequisites:**
<!-- ALL-CONTRIBUTORS-LIST:END -->
* [Download](https://git-scm.com/downloads) and install Git
* [Apply for a Gitlab account](https://gitlab.cern.ch/)
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
**The working flow of Git:**
* Initialise your repository with `git init[directory]`
* Clone a repository onto your local machine with `git clone [URL]`
* Edit the docs using Mkdocs
* Stage all changes for the next conmmit with `git add [directory]`
* Commit the staged snapshot with `git commit -m ["commit message"]`
* If others have modified it, you can **check the updates** with `git fetch` and **update the resource** with `git pull`.
* Show unstaged changes between your index and working directory with `git diff`
* Review your changes before submitting with `git status`
* Push your changes to the remote Gitlab repository with `git push`
![gitFlow](https://i.stack.imgur.com/ODFYa.png)
[https://laconga.redclara.net/courses/index.html](https://laconga.redclara.net/courses/index.html)
Reference to [git cheat sheet](file:///C:/Users/User/Downloads/atlassian-git-cheatsheet.pdf) for details
---
# Utilizando MkDocs en tu propio computador
## Requirement:
### MkDocs:
### Get it in https://www.mkdocs.org/
* Follow the instructions below in section **Building your project documentation**
### **For Latex-kind and Maths**
* ```python-markdown-math```
Get it (install using ```pip```) as mentioned in: https://github.com/mitya57/python-markdown-math
---
**Once you get those installed**:
You can follow this instruction:
``` shell
git clone https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs.git
cd tutorial-mkdocs
mkdocs serve
```
To put it in App, you need to generate HTML by:
```
mkdocs build
```
---
# Building your project documentation
[**MkDocs**](https://www.mkdocs.org) is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation.
Documentation source files are written in **Markdown**, and configured with a single YAML configuration file.
## **Mkdocs installation**
* **Prerequisite: Python and Pip**
In order to manually install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have these already installed from the command line:
**On Windows:**
```
C:\Users\User>python --version
Python 3.5.4
C:\Users\User>pip --version
pip 9.0.1
```
**On MacOS or Linux**
```
$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2
```
* **Installing Python**
Install [Python](https://www.python.org/) by downloading an installer appropriate for your system from [python.org](https://www.python.org/downloads/) and running it.
**Note:**
If you are installing Python on Windows, be sure to check the box to have Python added to your PATH if the installer offers such an option (it's normally off by default).
![path](https://www.mkdocs.org/img/win-py-install.png)
* **Installing Pip**
If you're using a recent version of Python, the Python package manager, pip, is most likely installed by default. However, you may need to upgrade pip to the lasted version:
`pip install --upgrade pip`
If you need to install pip for the first time, download get-pip.py. Then run the following command to install it:
`python get-pip.py`
* **Installing MkDocs**
Install the `mkdocs` package using pip:
```
pip install mkdocs
```
You should now have the `mkdocs` command installed on your system. Run `mkdocs--version` to check whether successfully installed.
**On Windows:**
```
C:\Users\User>mkdocs --version
mkdocs, version 1.0.4
```
**On MacOS or Linux**
```
$ mkdocs --version
mkdocs, version 0.15.3
```
## **Getting started to edit**
* Clone this documentation to your device by git
Clone with https:
```
git clone git clone https://github.com/LA-CoNGA-MiLab-RedClara/tutorial-mkdocs.git
cd tutorial-mkdocs
```
In your `docs` folder, you will see a configuration file named `mkdocs.yml`, and a folder named `docs` that will contain your documentation source files.
![folder1](https://github.com/veritasalice/MarkdownPhotos/blob/master/folder1.png?raw=true)
Right now the `docs` folder just contains all the documentation pages, such as `index.md`, `datasets.md` and the folders where the pages are saved.
![folder2](https://github.com/veritasalice/MarkdownPhotos/blob/master/folder2.png?raw=true)
MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` configuration file, and then start the server by running the `mkdocs serve` command:
```
C:\Users\User\tutorial-mkdocs>mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 190705 15:13:53 server:296] Serving on http://127.0.0.1:8000
[I 190705 15:13:53 handlers:62] Start watching changes
[I 190705 15:13:53 handlers:64] Start detecting changes
```
Open up `http://127.0.0.1:8000/` in your browser, and you'll see the pages you cloned being displayed:
![pic3](https://gitmilab.redclara.net/tutoriales/tutorial-mkdocs/blob/master/docs/images/la-conga.png?raw=true)
Use the editor you like to edit the files in `docs` and your changes will be displayed when saving them.
## **Using the Git to commit your changes**
By far, the most widely used modern version control system in the world today is Git.
In Git, every developer's working copy of the code is also a repository that can contain the full history of all changes.
**Prerequisites:**
* [Download](https://git-scm.com/downloads) and install Git
* [Apply for a Gitlab account](https://gitlab.cern.ch/)
**The working flow of Git:**
* Initialise your repository with `git init[directory]`
* Clone a repository onto your local machine with `git clone [URL]`
* Edit the docs using Mkdocs
* Stage all changes for the next conmmit with `git add [directory]`
* Commit the staged snapshot with `git commit -m ["commit message"]`
* If others have modified it, you can **check the updates** with `git fetch` and **update the resource** with `git pull`.
* Show unstaged changes between your index and working directory with `git diff`
* Review your changes before submitting with `git status`
* Push your changes to the remote Gitlab repository with `git push`
![gitFlow](https://i.stack.imgur.com/ODFYa.png)
Reference to [git cheat sheet](file:///C:/Users/User/Downloads/atlassian-git-cheatsheet.pdf) for details
---
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment