Ce document aborde le processus de contribution aux articles et exemples de code qui sont hébergés sur le site de la documentation ASP.NET. Les corrections de fautes de frappe et les nouveaux articles sont des contributions bienvenues.
Les articles sont stockés dans le dépôt en tant que fichiers Markdown. Pour apporter des modifications simples au contenu d’un fichier Markdown, dans le navigateur, vous devez sélectionner le lien Modifier dans le coin supérieur droit de la fenêtre du navigateur. (Dans une fenêtre de navigateur étroite, développez la barre Options pour voir le lien Modifier.) Suivez les instructions pour créer une demande de tirage (pull request). Nous examinerons la demande de tirage et l’accepterons ou suggérerons des modifications.
Vous devez avoir une connaissance élémentaire de Git et GitHub.com.
- Ouvrez un problème décrivant ce que vous voulez faire, par exemple changer un article existant ou en créer un. Nous demandons souvent le plan des nouvelles rubriques suggérées. Attendez l’approbation de l’équipe avant de vous investir davantage.
- Dupliquez (fork) le dépôt aspnet/Docs et créez une branche pour vos modifications.
- Soumettez une demande de tirage dans la branche master avec vos modifications.
- Si votre demande de tirage se voit attribuer l’étiquette « cla-required », signez le contrat CLA (Contribution License Agreement).
- Répondez aux commentaires sur la demande de tirage.
Pour obtenir un exemple où ce processus a conduit à la publication d’un nouvel article, consultez le problème #67 et la demande de tirage #798 dans le dépôt .NET Docs. Le nouvel article est Documentation de votre code.
Si vous utilisez Visual Studio Code pour contribuer à la documentation ASP.NET, vous pouvez augmenter votre productivité en installant l’extension Docs Authoring Pack. L’extension fournit un éventail d’outils qui facilitent la vérification (linting) du code Markdown, la vérification orthographique du code et l’utilisation des modèles d’article.
Les articles sont écrits en DFM (DocFX Flavored Markdown), qui est un sur-ensemble de GFM (GitHub Flavored Markdown). Pour obtenir des exemples de syntaxe DFM illustrant les fonctionnalités de l’interface utilisateur couramment utilisées dans la documentation ASP.NET, consultez Metadata and Markdown Template dans le guide de style du dépôt .NET Docs.
Pour chaque fichier Markdown, un dossier pour les images et un dossier pour l’exemple de code peuvent exister. Si l’article est fundamentals/configuration/index.md, les images se trouvent dans fundamentals/configuration/index/_static, tandis que les exemples de fichiers de projet d’application se trouvent dans fundamentals/configuration/index/sample. Une image dans le fichier fundamentals/configuration/index.md est affichée par le code Markdown suivant :
Toutes les images doivent avoir un texte de remplacement (alt). Pour obtenir des conseils sur la spécification du texte de remplacement, consultez les ressources en ligne, telles que WebAIM: Alternative Text (WebAIM : texte de remplacement).
Utilisez des minuscules pour les noms de fichiers Markdown et les noms de fichiers image.
Les liens internes doivent utiliser l’uid de l’article cible avec un lien xref (le texte du lien est défini sur le titre du contenu lié) :
<xref:uid_of_the_topic>Si le titre de l’article ne convient pas pour le texte du lien (par exemple, un mot ou une expression dans une phrase est le texte du lien), spécifiez le lien xref et le texte du lien comme suit :
[link text](xref:uid_of_the_topic)Pour plus d’informations, consultez DocFX Cross Reference.
N’incluez pas d’images avec les articles, sauf :
- Dans les tutoriels d’intégration de base (débutant).
- Quand une image est nécessaire par souci de clarté.
Ces restrictions réduisent la taille du dépôt.
Éventuellement, assurez-vous que les images et les captures d’écran utilisées dans la documentation sont compressées, ce qui permet de réduire la taille des fichiers et d’optimiser le chargement des pages. Parmi les outils connus, citons TinyPNG (utilisable par le biais du site web TinyPNG ou de l’API TinyPNG) ou l’extension Visual Studio Image Optimizer.
Les articles contiennent souvent des extraits de code pour illustrer les points abordés. DFM vous permet de copier le code dans le fichier Markdown ou de faire référence à un fichier de code distinct. Nous préférons l’utilisation de fichiers de code distincts si possible afin de limiter les risques d’erreurs dans le code. Les fichiers de code sont stockés dans le dépôt, conformément à la structure de dossiers décrite précédemment pour les exemples de projets.
Les exemples suivants illustrent la syntaxe d’extraits de code DFM à utiliser dans un fichier configuration/index.md.
Pour afficher un fichier de code entier en tant qu’extrait de code :
[!code-csharp[](configuration/index/sample/Program.cs)]Pour afficher une partie d’un fichier en tant qu’extrait de code à l’aide de numéros de ligne :
[!code-csharp[](configuration/index/sample/Program.cs?range=1-10,20,30,40-50]
[!code-html[](configuration/index/sample/Views/Home/Index.cshtml?range=1-10,20,30,40-50]Pour les extraits de code C#, référencez une région C#. Si possible, utilisez des régions plutôt que des numéros de ligne, car les numéros de ligne dans un fichier de code ont tendance à changer au point de ne plus être synchronisés avec les références de numéro de ligne dans un fichier Markdown. Les régions C# peuvent être imbriquées. Si vous référencez la région externe, les directives #region et #endregion internes ne sont pas affichées dans un extrait de code.
Pour afficher une région C# nommée « snippet_Example » :
[!code-csharp[](configuration/index/sample/Program.cs?name=snippet_Example)]Pour mettre en surbrillance les lignes sélectionnées dans un extrait de code affiché (généralement sous la forme d’un arrière-plan jaune) :
[!code-csharp[](configuration/index/sample/Program.cs?name=snippet_Example&highlight=1-3,10,20-25)]
[!code-csharp[](configuration/index/sample/Program.cs?range=10-20&highlight=1-3]
[!code-html[](configuration/index/sample/Views/Home/Index.cshtml?range=10-20&highlight=1-3]
[!code-javascript[](configuration/index/sample/UsingOptionsSample.csproj?range=10-20&highlight=1-3]Testez vos modifications avec l’outil en ligne de commande DocFX, qui crée une version hébergée localement du site. DocFX n’affiche pas le style et les extensions de site créés pour docs.microsoft.com.
DocFX nécessite :
- .NET Framework sur Windows.
- Mono pour Linux ou macOS.
-
Téléchargez et décompressez docfx.zip à partir des versions DocFX.
-
Ajoutez DocFX à votre chemin (PATH).
-
Dans un shell de commande, accédez au dossier qui contient le fichier docfx.json (aspnet pour du contenu ASP.NET ou aspnetcore pour du contenu ASP.NET Core) et exécutez la commande suivante :
docfx --serve -
Dans un navigateur, accédez à
http://localhost:8080/group1-dest/.
-
Installez Mono via Homebrew :
brew install mono -
Téléchargez la dernière version de DocFX.
-
Extrayez l’archive dans $HOME/bin/docfx.
-
Créez une paire d’alias pour docfx dans un interpréteur de commandes bash. Le premier alias est utilisé pour générer la documentation. Le deuxième alias est utilisé pour générer et diffuser la documentation.
alias docfx='mono $HOME/bin/docfx/docfx.exe' alias docfx-serve='mono $HOME/bin/docfx/docfx.exe --serve'
-
Dans un shell de commande, accédez au dossier qui contient le fichier docfx.json (aspnet pour du contenu ASP.NET ou aspnetcore pour du contenu ASP.NET Core) et exécutez la commande suivante pour créer et diffuser les documents via son alias :
docfx-serve -
Dans un navigateur, accédez à
http://localhost:8080/group1-dest/.
Notre objectif est d’écrire une documentation facile à comprendre par le plus grand nombre. À cette fin, nous avons établi des instructions sur le style que nos collaborateurs sont invités à suivre. Pour plus d’informations, consultez Voice and tone guidelines dans le dépôt .NET.
Le Guide de style d’écriture Microsoft fournit des instructions sur le style et la terminologie pour toutes les formes de communication au sujet d’une technologie, notamment la documentation ASP.NET Core.
Si vous supprimez un article, changez son nom de fichier ou déplacez-le vers un autre dossier, créez une redirection afin que les personnes qui ont créé un signet pour l’article ne reçoivent pas une erreur 404 Non trouvé. Ajoutez les redirections au fichier de redirection dans la branche master.