update contribution guide

jakobkogler · jakobkogler · commit 12c42888b4d8 · 2022-01-08T22:47:35.000+01:00
diff --git a/README.md b/README.md
@@ -12,15 +12,3 @@ Translation of http://e-maxx.ru into English
 Compiled pages are published at https://cp-algorithms.com/
 
 Manual for contributors: https://cp-algorithms.com/contrib.html
-
-## Prerequisits
-
-```sh
-pip install mkdocs-material
-```
-
-## Compile pages
-
-```sh
-mkdocs serve
-```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -27,6 +27,9 @@ markdown_extensions:
   - pymdownx.highlight
   - pymdownx.superfences
   - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji 
+      emoji_generator: !!python/name:materialx.emoji.to_svg
 extra_javascript:
   - javascript/config.js
   - https://polyfill.io/v3/polyfill.min.js?features=es6
diff --git a/src/contrib.md b/src/contrib.md
@@ -7,88 +7,54 @@ hide:
 
 ## General information
 
-We collaborate via means of github.
+This website (articles, design, ...) is developed via [Github](https://github.com/e-maxx-eng/e-maxx-eng). And everybody is welcome to help out. All you need is a Github account.
 
 Generated pages are compiled and published at [https://cp-algorithms.com](https://cp-algorithms.com).
 
-And sources (to which you may want to contribute) are [here](http://github.com/e-maxx-eng/e-maxx-eng/tree/master/src).
-
 In order to make contribution consider the following steps:
 
-1. Fork [source repository](https://github.com/e-maxx-eng/e-maxx-eng).
-2. Add or modify files in `src` subfolder in Markdown format (you can do this in web-interface of github now).
-3. Make sure you added `<!--?title ... -->` to your page and the corresponding link to main (index) page.
-3. Use [Test-Your-Page form](./preview.html) to check if you are satisfied with the result.
-4. Use `pull-request` feature to send the request for your changes to be merged.
-5. It may take few hours or few days before someone who have admin rights will merge your request. Contact any of admins personally to speed up this process!
-6. After merging it will take about 5 minutes before updated html page will appear at the site.
-
-**You may start with this [demo-article](demo-article.md) or even use [its source](https://raw.githubusercontent.com/e-maxx-eng/e-maxx-eng/master/src/contrib.md) as a template for your new article.**
-
-Please kindly refer to manuals on using `git` and `github` anywhere over internet. You may also watch this demo video:
+1. Go to an article that you want to change, and click the pencil icon :material-pencil: next to the article title.
+2. Fork the repository if requested.
+3. Modify the article.
+4. Use the [preview page](./preview.html) to check if you are satisfied with the result.
+5. Make a commit by clicking the _Propose changes_ button.
+6. Create a pull-request by clicking the _Compare & pull request_ button.
+7. Somebody from the core team will look over the changes. This might take a few hours/days.
 
-<div style="text-align:center">
-<iframe width="420" height="315" src="https://www.youtube.com/embed/TrBBw4J9X30" frameborder="0" allowfullscreen></iframe>
-</div>
+In case you want to make some bigger changes, like adding a new article, or edit multiple files, you should fork the project in the traditional way, create a branch, modify the files in the Github UI or locally on your computer, and create a pull-request.
+If you are unfamiliar with the workflow, read [Step-by-step guide to contributing on GitHub](https://www.dataschool.io/how-to-contribute-on-github/).
 
-## Your Authorship is Preserved
+In case you are adding a new article, start by copying some other article in order to have the required header lines, and make sure to link to the article from the main (index.md) page.
 
-Some contributors add explicit links to their profiles at the bottom of the translated articles. However it is discouraged and simply not very convenient if the article was edited by several people. Every page has `Page Authors` link in its top - this link leads to the github commit history, so it is always easy to determine or prove the authorship (even of any single line). Just make sure that your GitHub profile (which is mentioned in history) provides enough information about you.
+## Syntax
 
-## Source format
+We use [Markdown](https://daringfireball.net/projects/markdown) for the articles, and use the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to render the Markdown articles into HTML.
 
-We use [Markdown](https://daringfireball.net/projects/markdown) for source texts and
-convert them automatically to HTML.
-Some [extra](https://michelf.ca/projects/php-markdown/extra/) features also could be used.
+For advanced Markdown features of Material for MkDocs see their [reference pages](https://squidfunk.github.io/mkdocs-material/reference/formatting), like:
 
-Formulas could be added thanks to `MathJax` library. Simply use `TeX` expressions inside single or double dollar marks `$`, for example:
+- [Math formulas with MathJax](https://squidfunk.github.io/mkdocs-material/reference/mathjax/#usage)
+  Notice that you need to have an empty line before and after a `$$` math block.
+- [Data tables](https://squidfunk.github.io/mkdocs-material/reference/data-tables/#usage)
 
-here is an inline equation: $P \ne NP$
-
-And here is the formula in the separate block:
-
-$$E = mc^{2}$$
+However not everything of the features should be used, and some of the features are not enabled or require a paid subscription.
 
 ## Some conventions
 
 * We have agreed as of issue [#83](https://github.com/e-maxx-eng/e-maxx-eng/issues/83) to express binomial coefficients with `\binom{n}{k}` instead of `C_n^k`. The first one renders as $\binom{n}{k}$ and is a more universal convention. The second would render as $C_n^k$.
 
 ## Adding Problems
-Try to add problems in ascending order of their difficulty. If you don't have enough time to do so, still add the problem. Lets hope that the next person will sort them accordingly.
-
-## Adding images
-
-Small images could be pushed along with texts to the [/img](https://github.com/e-maxx-eng/e-maxx-eng/tree/master/img) subfolder. Let them be in `PNG` format and less than `200kb`. Then you can refer to them inside the article with the tag:
-
-    ![some image description](&imgroot&/my-image.png)
-
-Here `my-image.png` should be your file name, while `&imgroot&` is some magic which will expand to proper url prefix when shown at the site (so you need not know the precise prefix of github raw data).
-
-Larger images should be posted to some image-hosting, like [PostImage](http://postimage.org) or [ImgUr](http://imgur.com/) - they will then give you the url to insert into the page.
 
-## Modifying CSS and JS files
-
-This is not something you usually need to do, when just writing content. It is rather for exceptional cases there arose necessity to improve general page style or behavior. These files are (due to certain technical reasons) in the other branch of the same github repository: https://github.com/e-maxx-eng/e-maxx-eng/tree/gh-pages - please, be careful here, as usually changes will affect the whole site. Also make sure site's cache and your browser cache is expired after changes done, otherwise testing could be bewildering.
-
-## Creating anchors and link to them
-
-It is possible to generate HTML anchors for sections of an article.
-E.g. the following generates a header and a named anchor.
-
-    ## Implementation ## {#implementation}
-
-And then link to it from the same or a different article:
-
-    For more detail read the [Implementation](#implementation).
-    More infos in [Impl. of Segmenttree](./data_structures/segment_tree.html#implementation).
-
-## Page Template
+Try to add problems in ascending order of their difficulty. If you don't have enough time to do so, still add the problem. Lets hope that the next person will sort them accordingly.
 
-Template for the pages (the one which creates small violet header and footer, determines the layout of the text, includes css and js files) is now also stored in this repo, in [src/\_templates](https://github.com/e-maxx-eng/e-maxx-eng/tree/master/src/_templates) folder. So in case you find some bugs in it, or with the passing of time some new features may be needed in it - create PR to improve it. Note that for testing purposes the alternative template could be created and used for specific page with the inclusion of special comment as shown below:
+## Local development
 
- `<!--?template myfunnytemplate-->`
+You can render the pages very easily also locally.
+All you need is Python, with the installed `mkdocs-material` package.
 
-The templates are cached for about 3600 seconds, rather than 300 seconds for ordinary pages, so be patient :)
+```console
+$ pip install mkdocs-material
+$ mkdocs serve
+```
 
 ## Tests
 
@@ -98,7 +64,7 @@ This way we can make sure that the snippets actually work, and don't contain any
 Creating tests works like this:
 You have to name each snippet that you want to test in the markdown article:
 
-    ```cpp snippet-name
+    ```{.cpp file=snippet-name}
     // some code
     ```
 
@@ -108,4 +74,17 @@ In the folder you can create a cpp file, that includes these snippets headers, a
 If the snippets don't work, the test program should return 1 instead of 0.
 
 You can run all tests with the script `test.sh`.
-Also, every pull-request will automatically tested via [Travis CI](https://travis-ci.org/e-maxx-eng/e-maxx-eng/), and the result of the tests will be shown.
+
+```console
+$ cd test
+$ ./test.sh
+Running test_aho_corasick.cpp - Passed in 635 ms
+Running test_balanced_brackets.cpp - Passed in 1390 ms
+Running test_burnside_tori.cpp - Passed in 378 ms
+...
+Running test_vertical_decomposition.cpp - Passed in 2397 ms
+
+51 PASSED in 49.00 seconds
+```
+
+Also, every pull-request will automatically tested via [Github Actions](https://travis-ci.org/e-maxx-eng/e-maxx-eng/).
