mirror of
https://github.com/ae-utbm/sith.git
synced 2025-07-09 19:40:19 +00:00
Rewrite documentation with MkDocs
This commit is contained in:
thomas girod
187
core/fixtures/SYNTAX.html
Normal file
187
core/fixtures/SYNTAX.html
Normal file
@ -0,0 +1,187 @@
|
||||
<p>Cette page vise à documenter la syntaxe <em>Markdown</em> utilisée sur le site.</p>
|
||||
<h1>Markdown-AE Documentation</h1>
|
||||
<p>Le Markdown le plus standard se trouve documenté ici:
|
||||
<a href="https://www.markdownguide.org/basic-syntax">https://www.markdownguide.org/basic-syntax</a>.<br />
|
||||
Si cette page n'est pas exhaustive vis à vis de la syntaxe du site AE,
|
||||
elle a au moins le mérite de bien documenter le Markdown original.</p>
|
||||
<p>Le réel parseur du site AE est une version tunée de <a href="https://github.com/lepture/mistune">mistune</a>.<br />
|
||||
Les plus aventureux pourront aller lire ses <a href="https://github.com/lepture/mistune/blob/master/tests/fixtures">tests</a>
|
||||
afin d'en connaître la syntaxe le plus finement possible.<br />
|
||||
En pratique, cette page devrait déjà résumer une bonne partie.</p>
|
||||
<h2>Basique</h2>
|
||||
<ul>
|
||||
<li>Mettre le texte en <strong>gras</strong> : <code>**texte**</code></li>
|
||||
<li>Mettre le texte en <em>italique</em> : <code>*texte*</code></li>
|
||||
<li><u>Souligner</u> le texte : <code>__texte__</code></li>
|
||||
<li><del>Barrer du texte</del> : <code>~~texte~~</code></li>
|
||||
<li>On peut bien sûr tout <del><em><strong><u>combiner</u></strong></em></del> : <code>~~***__texte__***~~</code></li>
|
||||
<li>Mettre du texte^en exposant^ : <code><sup>texte</sup></code></li>
|
||||
<li>Mettre du texte~en indice~ : <code><sub>texte</sub></code></li>
|
||||
</ul>
|
||||
<h2>Liens</h2>
|
||||
<ul>
|
||||
<li>Les liens simples sont détectés automatiquement : <code>http://www.site.com</code></li>
|
||||
</ul>
|
||||
<p><a href="http://www.site.com">http://www.site.com</a></p>
|
||||
<ul>
|
||||
<li>Il est possible de nommer son lien : <code>[nom du lien](http://www.site.com)</code></li>
|
||||
</ul>
|
||||
<p><a href="http://www.site.com">nom du lien</a></p>
|
||||
<ul>
|
||||
<li>Les liens peuvent être internes au site de l'AE, on peut dès lors éviter d'entrer
|
||||
l'adresse complète d'une page : <code>[nom du lien](page://nomDeLaPage)</code></li>
|
||||
</ul>
|
||||
<p><a href="/page/nomDeLaPage/">nom du lien</a></p>
|
||||
<ul>
|
||||
<li>On peut également utiliser une image pour les liens :
|
||||
<code>[nom du lien](options)</code></li>
|
||||
</ul>
|
||||
<p>[nom du lien](options)</p>
|
||||
<h2>Titres</h2>
|
||||
<ul>
|
||||
<li>Plusieurs niveaux de titres sont possibles</li>
|
||||
</ul>
|
||||
<pre><code># Titre de niveau 1
|
||||
## Titre de niveau 2
|
||||
### Titre de niveau 3
|
||||
etc...
|
||||
</code></pre>
|
||||
<h1>Titre de niveau 1</h1>
|
||||
<h2>Titre de niveau 2</h2>
|
||||
<h3>Titre de niveau 3</h3>
|
||||
<h2>Paragraphes et sauts de ligne</h2>
|
||||
<p>Un nouveau paragraphe se fait avec deux retours à la ligne.</p>
|
||||
<p>Un saut de ligne se force avec au moins deux espaces en fin de ligne.</p>
|
||||
<h2>Listes</h2>
|
||||
<p>Il est possible de créer des listes :</p>
|
||||
<h3>ordonnées :</h3>
|
||||
<pre><code>1. élément
|
||||
2. élément
|
||||
3. élément
|
||||
</code></pre>
|
||||
<ol>
|
||||
<li>élément</li>
|
||||
<li>élément</li>
|
||||
<li>élément</li>
|
||||
</ol>
|
||||
<p>Vous pouvez marquer plus simplement comme suit, les numéros se faisant tout seuls:</p>
|
||||
<pre><code>1. élément
|
||||
1. élément
|
||||
1. élément
|
||||
</code></pre>
|
||||
<ol>
|
||||
<li>élément</li>
|
||||
<li>élément</li>
|
||||
<li>élément</li>
|
||||
</ol>
|
||||
<h3>non ordonnées :</h3>
|
||||
<pre><code>- élément
|
||||
- élément
|
||||
- élément
|
||||
</code></pre>
|
||||
<ul>
|
||||
<li>élément</li>
|
||||
<li>élément</li>
|
||||
<li>élément</li>
|
||||
</ul>
|
||||
<h2>Tableaux</h2>
|
||||
<p>Un tableau est obtenu en respectant la syntaxe suivante :</p>
|
||||
<pre><code>| Titre | Titre2 | Titre3 |
|
||||
|-------|--------|--------|
|
||||
| test | test | test |
|
||||
| test | test | test |
|
||||
</code></pre>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Titre</th>
|
||||
<th>Titre2</th>
|
||||
<th>Titre3</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>test</td>
|
||||
<td>test</td>
|
||||
<td>test</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>test</td>
|
||||
<td>test</td>
|
||||
<td>test</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>L'alignement dans les cellules est géré comme suit, avec les ':' sur la ligne en dessous du titre:</p>
|
||||
<pre><code>| Titre | Titre2 | Titre3 |
|
||||
|:-------|:------:|-------:|
|
||||
| gauche | centre | droite |
|
||||
</code></pre>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th style="text-align:left">Titre</th>
|
||||
<th style="text-align:center">Titre2</th>
|
||||
<th style="text-align:right">Titre3</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td style="text-align:left">gauche</td>
|
||||
<td style="text-align:center">centre</td>
|
||||
<td style="text-align:right">droite</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h2>Images et contenus</h2>
|
||||
<p>Une image est insérée ainsi : <code></code>
|
||||
<img src="/static/core/img/logo.png" alt="texte alternatif" title="titre optionnel" /></p>
|
||||
<p>On peut lui spécifier ses dimensions de plusieurs manières :</p>
|
||||
<pre><code>
|
||||
|
||||
|
||||
</code></pre>
|
||||
<p><img src="/static/core/img/logo.png" alt="image à 50%" title="Image à 50%" style="width:50%;" /><br />
|
||||
Image à 50% de la largeur de la page.</p>
|
||||
<p><img src="/static/core/img/logo.png" alt="image de 350 pixels de large" title="Image de 350 pixels" style="width:350px;" /><br />
|
||||
Image de 350 pixels de large.</p>
|
||||
<p><img src="/static/core/img/logo.png" alt="image de 350x100 pixels" title="Image de 350x100 pixels" style="width:350px;height:100px;" /><br />
|
||||
Image de 350x100 pixels.</p>
|
||||
<p>(devrait pouvoir détecter si vidéo ou non)</p>
|
||||
<h2>Blocs de citations</h2>
|
||||
<p>Un bloc de citation se crée ainsi :</p>
|
||||
<pre><code>> Ceci est
|
||||
> un bloc de
|
||||
> citation
|
||||
</code></pre>
|
||||
<blockquote>
|
||||
<p>Ceci est
|
||||
un bloc de
|
||||
citation</p>
|
||||
</blockquote>
|
||||
<p>Il est possible d'intégrer de la syntaxe Markdown-AE dans un tel bloc.</p>
|
||||
<h2>Note de bas de page</h2>
|
||||
<p>On les crée comme ça<sup class="footnote-ref" id="fnref-1"><a href="#fn-1">1</a></sup>:</p>
|
||||
<pre><code>Je fais une note[^clef].
|
||||
|
||||
[^clef]: je note ensuite où je veux le contenu de ma clef qui apparaîtra quand même en bas
|
||||
</code></pre>
|
||||
<p>Vous pouvez aussi utiliser des numéros pour nommer vos clefs.</p>
|
||||
<pre><code>Note plus complexe[^1]
|
||||
|
||||
[^1]:
|
||||
je peux même faire des blocs
|
||||
sur plusieurs lignes, comme d'habitude!
|
||||
</code></pre>
|
||||
<h2>Échapper des caractères</h2>
|
||||
<ul>
|
||||
<li>Il est possible d'ignorer un caractère spécial en l'échappant à l'aide d'un \</li>
|
||||
<li>L'échappement de blocs de codes complet se fera à l'aide de balises <nosyntax></nosyntax></li>
|
||||
</ul>
|
||||
<h2>Autres (hérité de l'ancien wiki)</h2>
|
||||
<p>Une ligne peut être créée avec une ligne contenant 4 tirets (<code>----</code>).</p>
|
||||
<section class="footnotes">
|
||||
<ol>
|
||||
<li id="fn-1"><p>ceci est le contenu de ma clef<a href="#fnref-1" class="footnote">↩</a></p></li>
|
||||
</ol>
|
||||
</section>
|
||||
202
core/fixtures/SYNTAX.md
Normal file
202
core/fixtures/SYNTAX.md
Normal file
@ -0,0 +1,202 @@
|
||||
Cette page vise à documenter la syntaxe *Markdown* utilisée sur le site.
|
||||
|
||||
# Markdown-AE Documentation
|
||||
|
||||
Le Markdown le plus standard se trouve documenté ici:
|
||||
https://www.markdownguide.org/basic-syntax.
|
||||
Si cette page n'est pas exhaustive vis à vis de la syntaxe du site AE,
|
||||
elle a au moins le mérite de bien documenter le Markdown original.
|
||||
|
||||
Le réel parseur du site AE est une version tunée de [mistune](https://github.com/lepture/mistune).
|
||||
Les plus aventureux pourront aller lire ses [tests](https://github.com/lepture/mistune/blob/master/tests/fixtures)
|
||||
afin d'en connaître la syntaxe le plus finement possible.
|
||||
En pratique, cette page devrait déjà résumer une bonne partie.
|
||||
|
||||
## Basique
|
||||
|
||||
- Mettre le texte en **gras** : `**texte**`
|
||||
- Mettre le texte en *italique* : `*texte*`
|
||||
- __Souligner__ le texte : `__texte__`
|
||||
- ~~Barrer du texte~~ : `~~texte~~`
|
||||
- On peut bien sûr tout ~~***__combiner__***~~ : `~~***__texte__***~~`
|
||||
- Mettre du texte^en exposant^ : `<sup>texte</sup>`
|
||||
- Mettre du texte~en indice~ : `<sub>texte</sub>`
|
||||
|
||||
|
||||
## Liens
|
||||
|
||||
- Les liens simples sont détectés automatiquement : `http://www.site.com`
|
||||
|
||||
http://www.site.com
|
||||
|
||||
- Il est possible de nommer son lien : `[nom du lien](http://www.site.com)`
|
||||
|
||||
[nom du lien](http://www.site.com)
|
||||
|
||||
- Les liens peuvent être internes au site de l'AE, on peut dès lors éviter d'entrer
|
||||
l'adresse complète d'une page : `[nom du lien](page://nomDeLaPage)`
|
||||
|
||||
[nom du lien](page://nomDeLaPage)
|
||||
|
||||
- On peut également utiliser une image pour les liens :
|
||||
`[nom du lien](options)`
|
||||
|
||||
[nom du lien](options)
|
||||
|
||||
|
||||
|
||||
## Titres
|
||||
|
||||
- Plusieurs niveaux de titres sont possibles
|
||||
|
||||
```
|
||||
# Titre de niveau 1
|
||||
## Titre de niveau 2
|
||||
### Titre de niveau 3
|
||||
etc...
|
||||
```
|
||||
# Titre de niveau 1
|
||||
## Titre de niveau 2
|
||||
### Titre de niveau 3
|
||||
|
||||
## Paragraphes et sauts de ligne
|
||||
|
||||
Un nouveau paragraphe se fait avec deux retours à la ligne.
|
||||
|
||||
Un saut de ligne se force avec au moins deux espaces en fin de ligne.
|
||||
|
||||
|
||||
## Listes
|
||||
|
||||
Il est possible de créer des listes :
|
||||
|
||||
### ordonnées :
|
||||
|
||||
```
|
||||
1. élément
|
||||
2. élément
|
||||
3. élément
|
||||
```
|
||||
1. élément
|
||||
1. élément
|
||||
1. élément
|
||||
|
||||
Vous pouvez marquer plus simplement comme suit, les numéros se faisant tout seuls:
|
||||
```
|
||||
1. élément
|
||||
1. élément
|
||||
1. élément
|
||||
```
|
||||
|
||||
1. élément
|
||||
1. élément
|
||||
1. élément
|
||||
|
||||
|
||||
### non ordonnées :
|
||||
|
||||
```
|
||||
- élément
|
||||
- élément
|
||||
- élément
|
||||
```
|
||||
- élément
|
||||
- élément
|
||||
- élément
|
||||
|
||||
|
||||
## Tableaux
|
||||
|
||||
Un tableau est obtenu en respectant la syntaxe suivante :
|
||||
|
||||
```
|
||||
| Titre | Titre2 | Titre3 |
|
||||
|-------|--------|--------|
|
||||
| test | test | test |
|
||||
| test | test | test |
|
||||
```
|
||||
| Titre | Titre2 | Titre3 |
|
||||
|-------|--------|--------|
|
||||
| test | test | test |
|
||||
| test | test | test |
|
||||
|
||||
L'alignement dans les cellules est géré comme suit, avec les ':' sur la ligne en dessous du titre:
|
||||
|
||||
```
|
||||
| Titre | Titre2 | Titre3 |
|
||||
|:-------|:------:|-------:|
|
||||
| gauche | centre | droite |
|
||||
```
|
||||
| Titre | Titre2 | Titre3 |
|
||||
|:-------|:------:|-------:|
|
||||
| gauche | centre | droite |
|
||||
|
||||
|
||||
## Images et contenus
|
||||
|
||||
Une image est insérée ainsi : ``
|
||||
|
||||
|
||||
On peut lui spécifier ses dimensions de plusieurs manières :
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
Image à 50% de la largeur de la page.
|
||||
|
||||
|
||||
Image de 350 pixels de large.
|
||||
|
||||
|
||||
Image de 350x100 pixels.
|
||||
|
||||
(devrait pouvoir détecter si vidéo ou non)
|
||||
|
||||
## Blocs de citations
|
||||
|
||||
Un bloc de citation se crée ainsi :
|
||||
```
|
||||
> Ceci est
|
||||
> un bloc de
|
||||
> citation
|
||||
```
|
||||
|
||||
> Ceci est
|
||||
> un bloc de
|
||||
> citation
|
||||
|
||||
Il est possible d'intégrer de la syntaxe Markdown-AE dans un tel bloc.
|
||||
|
||||
## Note de bas de page
|
||||
|
||||
On les crée comme ça[^key]:
|
||||
|
||||
[^key]: ceci est le contenu de ma clef
|
||||
```
|
||||
Je fais une note[^clef].
|
||||
|
||||
[^clef]: je note ensuite où je veux le contenu de ma clef qui apparaîtra quand même en bas
|
||||
```
|
||||
Vous pouvez aussi utiliser des numéros pour nommer vos clefs.
|
||||
|
||||
```
|
||||
Note plus complexe[^1]
|
||||
|
||||
[^1]:
|
||||
je peux même faire des blocs
|
||||
sur plusieurs lignes, comme d'habitude!
|
||||
```
|
||||
|
||||
## Échapper des caractères
|
||||
|
||||
- Il est possible d'ignorer un caractère spécial en l'échappant à l'aide d'un \
|
||||
- L'échappement de blocs de codes complet se fera à l'aide de balises <nosyntax></nosyntax>
|
||||
|
||||
## Autres (hérité de l'ancien wiki)
|
||||
|
||||
Une ligne peut être créée avec une ligne contenant 4 tirets (`----`).
|
||||
@ -1,90 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
#
|
||||
# Copyright 2019
|
||||
# - Sli <antoine@bartuccio.fr>
|
||||
#
|
||||
# Ce fichier fait partie du site de l'Association des Étudiants de l'UTBM,
|
||||
# http://ae.utbm.fr.
|
||||
#
|
||||
# This program is free software; you can redistribute it and/or modify it under
|
||||
# the terms of the GNU General Public License a published by the Free Software
|
||||
# Foundation; either version 3 of the License, or (at your option) any later
|
||||
# version.
|
||||
#
|
||||
# This program is distributed in the hope that it will be useful, but WITHOUT
|
||||
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
||||
# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
|
||||
# details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License along with
|
||||
# this program; if not, write to the Free Sofware Foundation, Inc., 59 Temple
|
||||
# Place - Suite 330, Boston, MA 02111-1307, USA.
|
||||
#
|
||||
#
|
||||
|
||||
import os
|
||||
import signal
|
||||
import sys
|
||||
from http.server import CGIHTTPRequestHandler, test
|
||||
|
||||
from django.core.management.base import BaseCommand
|
||||
from django.utils import autoreload
|
||||
|
||||
|
||||
class Command(BaseCommand):
|
||||
help = "Generate Sphinx documentation and launch basic server"
|
||||
|
||||
default_addr = "127.0.0.1"
|
||||
default_port = "8080"
|
||||
|
||||
def add_arguments(self, parser):
|
||||
parser.add_argument(
|
||||
"addrport", nargs="?", help="Optional port number, or ipaddr:port"
|
||||
)
|
||||
|
||||
def build_documentation(self):
|
||||
os.chdir(os.path.join(self.project_dir, "doc"))
|
||||
err = os.system("make html")
|
||||
|
||||
if err != 0:
|
||||
self.stdout.write("A build error occured")
|
||||
|
||||
def start_server(self, **kwargs):
|
||||
os.chdir(os.path.join(self.project_dir, "doc", "_build/html"))
|
||||
addr = self.default_addr
|
||||
port = self.default_port
|
||||
if kwargs["addrport"]:
|
||||
addrport = kwargs["addrport"].split(":")
|
||||
|
||||
addr = addrport[0]
|
||||
|
||||
if len(addrport) > 1:
|
||||
port = addrport[1]
|
||||
|
||||
if not port.isnumeric():
|
||||
self.stdout.write("%s is not a valid port" % (port,))
|
||||
sys.exit(0)
|
||||
|
||||
test(HandlerClass=CGIHTTPRequestHandler, port=int(port), bind=addr)
|
||||
|
||||
def build_and_start_server(self, **kwargs):
|
||||
self.build_documentation()
|
||||
self.start_server(**kwargs)
|
||||
|
||||
def handle(self, *args, **kwargs):
|
||||
self.project_dir = os.getcwd()
|
||||
|
||||
signal.signal(signal.SIGTERM, lambda *args: sys.exit(0))
|
||||
try:
|
||||
if os.environ.get(autoreload.DJANGO_AUTORELOAD_ENV) == "true":
|
||||
reloader = autoreload.get_reloader()
|
||||
reloader.watch_dir(os.path.join(self.project_dir, "doc"), "**/*.rst")
|
||||
autoreload.logger.info(
|
||||
"Watching for file changes with %s", reloader.__class__.__name__
|
||||
)
|
||||
autoreload.start_django(reloader, self.build_and_start_server, **kwargs)
|
||||
else:
|
||||
exit_code = autoreload.restart_with_reloader()
|
||||
sys.exit(exit_code)
|
||||
except KeyboardInterrupt:
|
||||
pass
|
||||
@ -21,20 +21,19 @@
|
||||
#
|
||||
#
|
||||
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
from django.conf import settings
|
||||
from django.core.management.base import BaseCommand
|
||||
|
||||
from core.markdown import markdown
|
||||
|
||||
|
||||
class Command(BaseCommand):
|
||||
help = "Output the fully rendered doc/SYNTAX.md file"
|
||||
help = "Output the fully rendered SYNTAX.md file"
|
||||
|
||||
def handle(self, *args, **options):
|
||||
root_path = os.path.dirname(
|
||||
os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
|
||||
)
|
||||
with open(os.path.join(root_path) + "/doc/SYNTAX.md", "r") as md:
|
||||
root_path = Path(settings.BASE_DIR)
|
||||
with open(root_path / "core/fixtures/SYNTAX.md", "r") as md:
|
||||
result = markdown(md.read())
|
||||
print(result, end="")
|
||||
|
||||
@ -383,7 +383,7 @@ Welcome to the wiki page!
|
||||
# Adding syntax help page
|
||||
p = Page(name="Aide_sur_la_syntaxe")
|
||||
p.save(force_lock=True)
|
||||
with open(root_path / "doc" / "SYNTAX.md", "r") as rm:
|
||||
with open(root_path / "core" / "fixtures" / "SYNTAX.md", "r") as rm:
|
||||
PageRev(
|
||||
page=p, title="Aide sur la syntaxe", author=skia, content=rm.read()
|
||||
).save()
|
||||
|
||||
@ -14,7 +14,6 @@
|
||||
#
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import re
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
@ -131,9 +130,3 @@ markdown = mistune.create_markdown(
|
||||
"url",
|
||||
],
|
||||
)
|
||||
|
||||
if __name__ == "__main__":
|
||||
root_path = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
with open(os.path.join(root_path) + "/doc/SYNTAX.md", "r") as md:
|
||||
result = markdown(md.read())
|
||||
print(result, end="")
|
||||
|
||||
@ -215,9 +215,9 @@ def test_custom_markdown_syntax(md, html):
|
||||
|
||||
|
||||
def test_full_markdown_syntax():
|
||||
doc_path = Path(settings.BASE_DIR) / "doc"
|
||||
md = (doc_path / "SYNTAX.md").read_text()
|
||||
html = (doc_path / "SYNTAX.html").read_text()
|
||||
syntax_path = Path(settings.BASE_DIR) / "core" / "fixtures"
|
||||
md = (syntax_path / "SYNTAX.md").read_text()
|
||||
html = (syntax_path / "SYNTAX.html").read_text()
|
||||
result = markdown(md)
|
||||
assert result == html
|
||||
|
||||
|
||||
Reference in New Issue
Block a user