Aspnetcore: Quel format devons-nous utiliser pour la documentation ASP.NET 5 ?

http://shfb.codeplex.com

Ou créez simplement quelque chose de nouveau.

Un bon pré-processeur générant du GH Markdown serait excellent.

+1 pour Markdown (ou GitHub Flavored Markdown). Il manque peut-être certaines fonctionnalités mais il est assez bien connu et très facile à apprendre et à utiliser. Je suppose que cela peut dépendre de la décision finale sur l'endroit où il sera hébergé, car vous avez mentionné quelques options.

Salut Daniel,
Nous vous remercions de votre contribution.
En tant que développeur junior, je trouve qu'il est facile d'organiser des documents sous forme de titres dans la barre latérale, similaire à ceci http://rustbyexample.com/
(A MON HUMBLE AVIS)

-1 sur la fabrication de quelque chose de nouveau.
+1 pour travailler sur quelque chose d'existant et l'améliorer si possible.

@danroth27 Pouvez-vous partager un peu plus de détails sur vos besoins en documentation et sur les fonctionnalités d'un système de documentation mature dont vous avez besoin ?

Je pense que dire "utiliser Markdown" est trop simpliste.

Markdown est un DSL pour HTML. C'est tout. Diriez-vous vraiment "Docs est un problème résolu, utilisons HTML !"

Nous avons besoin d'un véritable système de documentation comme Sphinx.

• Markdown ne peut pas générer de table des matières.
• Markdown ne peut pas lier entre les sujets (vous devez faire les liens manuellement)
• Markdown ne peut pas faire des choses comme la prise en charge multilingue ou la prise en charge de plusieurs versions.

Je soutiens Read The Docs de @ericholscher , mais plus spécifiquement Sphinx et reStructuredText.

Ou utilisez Doxygen et vNext ne sortira jamais ;)

Qu'en est-il de quelque chose de similaire à Roslyn ou AngularJS ? http://source.roslyn.codeplex.com/ https://docs.angularjs.org/api

Markdown fonctionne très bien pour la plupart des autres projets sur GitHub. +1 pour Markdown.

@shanselman , liens relatifs ?

Je pense que l'utilisation de Sphinx fonctionnerait.
@issafram Exemples ici :
http://sphinx-doc.org/
https://docs.python.org/3/tutorial/index.html

@akoeplinger Nous aimerions quelque chose à partir duquel nous pouvons facilement générer une table des matières et relier facilement les pages. Nous aimerions également quelque chose qui puisse générer une variété de formats de documents, notamment HTML, PDF et ePub. Les documents doivent également être lisibles sur les appareils mobiles.

@issafram Markdown est génial lorsque vos documents font une centaine de pages, probablement moins. Mais des milliers de pages et des tables des matières imbriquées ? Tenir à jour les annexes ? Lier les docs ASP.NET et .NET ? Ce sera un gâchis.

Gardez à l'esprit, si vous voulez que ce soit vraiment open source, et donc quelque chose qui encourage la contribution, que le système doit être aussi simple que possible, sans courbe d'apprentissage. Markdown ne peut pas générer de table des matières par lui-même, mais un code relativement simple peut générer une table des matières à partir de Markdown.
Chez Orchard, nous sommes très satisfaits de notre système, qui est Markdown sur Github plus un site Azure avec très peu de code (pour l'indexation et la recherche Lucene, plus la génération de ToC) qui est automatiquement mis à jour chaque fois que le dépôt est poussé. Outils super simples et familiers.
La seule chose que je n'aime pas, c'est le manque de métadonnées (nous extrayons les titres des noms de fichiers), mais il existe également des solutions pour cela, comme les en-têtes YAML de Jeckyll (supportés par Github) ou mon propre format Snippable.

@issafram Cela ne fonctionne pas bien sur d'énormes bases de code avec BEAUCOUP de documents et de refactorisation par exemple. Renommer une classe et _bye bye_ liens relatifs.

_edit_ : Je suis en retard pour le jeu :P

Je suis heureux d'apprendre que la documentation ASP.NET comptera des milliers de pages ;) Pourtant, KISS.

@bleroy Jetez un œil à ceci http://read-the-docs.readthedocs.org/en/latest/ et le rST qui l'a créé. https://github.com/rtfd/readthedocs.org/blob/master/docs/index.rst

Bien sûr, c'est génial. Juste donner notre expérience. Je comprends que vous êtes à une autre échelle.

rST est la meilleure option ici, pratique. Comme il s'agit d'ASP.NET, avoir quelque chose d'assez intelligent pour mettre à jour ses index (du point de vue de la table des matières ou même du point de vue de la liste des classes) est probablement une priorité absolue.

Idéalement, j'exécuterais quelque chose dans le flux de travail de construction pour récupérer tous ces fichiers .XML générés à partir des fichiers binaires, puis les faire passer par un processeur pour générer les fichiers qui sont ensuite publiés sur un serveur. L'outillage exact... Je n'en ai aucune idée. Beaucoup ont été mentionnés. Je recommanderais de créer le vôtre et de l'ouvrir. Oui oui ... Construire vs acheter débat mais je déteste utiliser des outils qui ont des ressources non gérées comme certaines des ci-dessus. Quoi qu'il en soit, cela semble idéal... Vous avez probablement des contraintes de budget et de temps, etc.

@issafram Si vous finissez tous par utiliser Sphinx/RTD, quelque chose comme Breathe pourrait être une approche viable : http://breathe.readthedocs.org/en/latest/ -- c'est l'intégration avec Sphinx & Doxygen qui utilise le Fichiers XML Doxygen.

@issafram Il me semble que vous décrivez SHFB ... (En fait, Sandcastle , SHFB le rend simplement plus agréable à utiliser : P)

Oui, vous avez besoin d'un préprocesseur/postprocesseur, vous pouvez lier la relativité dans le document avec GHMD pour TOC. Pour nos projets, nous avons lancé le nôtre en prenant essentiellement .Net doc XML et une convention basée sur la fusion avec un exemple de code et d'autres contenus statiques écrits en MD. Le résultat final est HTML.

Avoir du code et du contenu éditorial statique dans MD faciliterait la réalisation de relations publiques. Ce que j'aime dans Markdown en tant que format source, c'est qu'il est beaucoup plus propre que HTML, XML, etc. Rend l'audit facile et bien adapté au contrôle de source.

Nous avons besoin d'un outil de documentation propre et simple basé sur une convention pour .Net, je n'en ai pas trouvé, s'il y en a un, j'aimerais être informé. Et serait heureux d'y contribuer.

En ce qui concerne la maintenabilité et la liaison entre les projets. Intersphinx est un moyen puissant de le faire de manière sémantique. Il vous permet de cataloguer toutes les références (qu'il s'agisse de code ou de prose) et de les lier explicitement à travers les projets.

Documents ici : http://sphinx-doc.org/latest/ext/intersphinx.html

C'est le genre de fonctionnalité que quelque chose comme Markdown n'a pas à ma connaissance.

Convenu que la démarque n'est pas la meilleure solution, mais pour l'instant nous avons besoin d'une solution simple. Allez, nous sommes des développeurs, nous pouvons donc étendre cela si nécessaire. Github prend en charge le démarquage, VSO prend désormais en charge le démarquage à partir de la vue code. Avons-nous vraiment besoin d'un débat. Désolé si je suis trop direct.

Démarque +1

@ctsni J'avoue, Markdown _felt_ comme le meilleur choix au premier coup d'œil/pensée. Mais plus j'y pense, plus j'ai l'impression d'essayer d'enfoncer une cheville carrée dans un trou rond.

Certes, je n'ai pas de bonne alternative, donc je m'excuse de ne pas avoir beaucoup contribué, mais même en étendant Markdown, je ne pense pas que nous nous retrouverions avec quelque chose du même Markdown joli, propre et soigné que nous avons maintenant _ étant donné le exigences_.

Il semble que vous souhaitiez reproduire la documentation MSDN existante dans un format open source ? Est-ce juste? Vous avez besoin d'une solution pour gérer les descriptions générales, les tutoriels, les exemples de code et la documentation de l'API ? Ou est-ce un sous-ensemble de cela?

Je ne suis pas convaincu qu'il existe une solution, plutôt une collection d'outils dont la sortie peut être combinée. Je peux voir ce que fait ReadTheDocs - rassembler plusieurs sources dans un ensemble cohérent de documentation. Donc Markdown est une réponse valable à une partie de la solution (c'est-à-dire les descriptions et les tutoriels), mais n'est-ce pas l'image complète ?

Question ouverte : est-il possible d'extraire les annexes et la table des matières directement du démarquage ? Cela ne me semble pas trop difficile ? Je suis biasée. Je n'ai pas travaillé sur un système avec des milliers de pages... Désolé @shanselman , je ne peux vraiment pas apporter de sagesse au-delà de ce que je sais.

@craignicol Rien de moins que la documentation MSDN actuelle serait, pour moi, une énorme déception. Je dis toujours à tout le monde que l'une des meilleures documentations (en termes de structure, de formulation et de tout ce qui s'y rapporte) se trouve sur MSDN. J'ai vu beaucoup de documentation, mais la plupart, sinon la totalité, ne se rapprochent même pas de la "qualité MSDN" (à mon humble avis, bien sûr). Cela dit : un facteur important est, bien sûr, que les personnes derrière les documents MSDN prennent si bien soin du _contenu_ réel de MSDN ; la structure, la mise en page, la conception et ce que vous avez vient en second lieu.

Peut-être tangentiel, mais ce serait très bien d'avoir quelque chose comme dash . Le développement Web évolue si vite et les nouvelles technologies s'influencent mutuellement que je me retrouve à chercher des informations ici et là sur Google. Être capable d'accéder à tout dans un seul endroit confiné qui peut être invoqué via quelques frappes est incroyablement utile. Il existe un effort similaire http://zealdocs.org/ pour Linux et Windows.

@craignicol D'accord, l'objectif est d'avoir des documents de qualité MSDN qui sont open-source et plus faciles à maintenir et à mettre à jour.

@ciriarte Il existe un support pour traduire les documents Sphinx en Dash : https://pypi.python.org/pypi/doc2dash -- Nous avons examiné la création automatique d'ensembles Dash sur RTD.org, mais nous ne l'avons pas encore déployé.

Je pense que @shanselman l'a mieux dit ci-dessus - Markdown n'est pas plus la réponse que HTML, Word ou .txt ne serait la réponse. Markdown est principalement une description de présentation - ce qu'il faut, c'est quelque chose pour générer le Markdown (ou HTML, document Word, fichier .txt, etc.)

Je suppose que ma question serait d'où voyez-vous que le contenu vient? Est-ce que ça va être écrit à la main ? Généré automatiquement à partir du code ? Intégré dans les commentaires ?

Je suis d'accord avec @craignicol une collection d'outils pour fusionner le contenu généré automatiquement avec des pages GH Markdown "statiques" pour les échantillons créés par l'homme et le contenu éditorial non disponible dans l'assemblage XML. Le résultat pourrait alors être html statique sur GHPages, PDF ou autre.
Le préprocesseur pourrait détecter tout contenu statique orphelin si le code est renommé/refactorisé Ie
La prise en charge de la langue pourrait être essentiellement des dossiers facultatifs avec la même structure que neutre. Les documents non traduits pourraient alors revenir au neutre ou passer par exemple Bing traduire.

En repensant à la suggestion originale, je serais d'accord avec @ danroth27 sur le démarquage pour le format et lisez la documentation pour la construction. Merci.

La flexibilité de readthedocs.org + Sphinx peut permettre une équivalence avec MSDN, sinon accessible.

@ciriarte Cela pourrait probablement également être pris en charge avec des archives exportables pour le lecteur MSDN.

@jalcine @ericholscher semble fantastique.

@RobThree J'espère que l'équipe qui gère actuellement les documents pourra être persuadée de passer au nouveau format, sinon cet exercice ne vaut pas la peine d'être fait.

@ctsni c'est possible - j'ai écrit un analyseur Markdown ToC en python, qui prend une liste de fichiers et génère un ToC. La partie délicate consiste à annoter les fichiers source afin que l'analyseur sache quoi extraire pour générer la table des matières et les annexes. Le format intermédiaire, que ce soit Markdown ou rST, n'est pas pertinent, c'est l'obtention des métadonnées qui est la clé.

En regardant les documents MSDN, les deux principaux éléments de métadonnées qui importent le plus pour les liens hypertexte sont les crochets d'API, pour permettre la traversée du code, et les crochets conceptuels (par exemple, la sécurité) qui créent un sujet pour englober l'API, les tutoriels, et les informations sur l'architecture. Si la partie API est bien faite, je suis sûr que le reste du contenu peut être adapté en conséquence. J'aime l'idée de Dash, mais je pense que ReadTheDocs et Sphinx sont les plus proches que j'ai vus de ce que j'aime chez MSDN, mais je pense qu'ils devront être adaptés pour gérer la riche structure de sujets et de didacticiels de MSDN.

Je m'interroge sur tout ce concept. Je veux dire, j'adore l'idée d'ouvrir la chaîne de documentation et d'impliquer la communauté, mais le faire en dehors de MSDN me donne un peu la frousse. Depuis ce qui semble être (et peut-être) le début de .NET, nous sommes passés à MSDN pour une référence canonique sur n'importe quelle API Microsoft. De WinForms à WebForms, tout est au même endroit, bien référencé et formaté de manière cohérente. Je ne peux pas m'empêcher de me demander si ce qui est gagné de cette entreprise fournira suffisamment d'avantages pour compenser la fragmentation et la perte de cohérence. Je ne dis pas que cela n'en vaudra pas la peine, et ces discussions ont probablement déjà eu lieu, mais matière à réflexion.

+1 pour le Sphinx

Je creuse vraiment le format et les outils readthedocs et ils fonctionnent très bien pour de nombreux projets. Ne réinventez pas la roue. Markdown c'est bien. Je pense que si vous ne pouvez pas le décrire avec Markdown, vous essayez de faire quelque chose de trop compliqué. Pour ma part, je serais heureux de contribuer si le format et le niveau de friction sont faibles. Le wiki MSDN était en quelque sorte en train d'y arriver, mais la majeure partie a été fermée et il est devenu un désert aride d'anciens contenus. La communauté PHP semble s'en sortir assez bien avec son système de documentation (bien que ses commentaires tombent parfois dans des terriers de lapin). Je pense que garder les choses simples avec Markdown fonctionnera, mais il doit probablement y avoir une sorte d'outil d'indexation/génération pour le "document maître" ou quelque chose pour le rassembler et le garder synchronisé. Presque comme un système de construction de dépendances pour des milliers d'extraits/documents de démarquage.

Je pense Markdown pour les fragments de texte. Yaml front-matter ou fichiers json pour les métadonnées. Processeur basé sur .NET personnalisé avec un modèle de plug-in extensible pour ajouter facilement une syntaxe pour des éléments fantaisistes comme la table des matières et les tables, etc. Ou utilisez simplement rst, assez similaire à Markdown.

Créez simplement MSDN Open Source. A moins que ce ne soit un gâchis :)

@somedave ne sais pas pour vous, mais j'ai de plus en plus de mal à trouver du contenu sur MSDN, en particulier une documentation architecturale de haut niveau sur des frameworks non actuels. Avoir la documentation liée au code, et tous les open source disponibles et sous contrôle de version est une amélioration massive.

Voulons-nous vraiment un autre MDSN du nouveau Microsoft ? Une grande partie de la documentation générée est une perte de temps. Ce dont il avait besoin, c'est d'un récit et d'exemples, mais cela manque souvent, ne laissant que les informations de base que j'ai déjà du système de type. Avec un accès facile à la source, nous pouvons maintenant découvrir ce que quelque chose fait vraiment de toute façon. Les articles, les explications et les exemples de test d'utilisation sont bien meilleurs, surtout s'ils sont créés en réponse à la demande, par exemple des questions de débordement de pile.

@ danroth27 , parlez-vous uniquement de la documentation javadoc/xmldoc, ou également de la documentation en général ? C'est-à-dire ce http://www.asp.net/aspnet/overview/authentication-and-identity vs https://msdn.microsoft.com/en-us/library/system.web.mvc.ivalueprovider (v=vs. 118).aspx?

Dgeni https://github.com/angular/dgeni

Certainement HTML mais avec la possibilité de l'utiliser localement - disons de l'installer sur le IIS local (ou juste localement).

S'il vous plaît, construisez sur le pipeline Sandcastle et SHFB et aidez-le à le rendre plus agréable (plus simple et "open source friendly"). La prise en charge de la création de démarques (pour le contenu conceptuel) et du rendu peut être ajoutée (certains débuts ont déjà été faits dans cette direction).
Il y a beaucoup de valeur dogfood dans la prise en charge des outils populaires basés sur .NET (un demi-million de téléchargements pour SHFB). Les idiomes fuient des outils vers le projet lui-même. Par exemple, avec .NET, il est vraiment utile de prendre en charge des extraits de code multilingues, afin que VB.NET et F # puissent être maintenus en tant que langages viables sur la plate-forme. Sandcastle et la sortie de style MSDN le font très bien.

Le problème avec reStructuredText est qu'il ressemble un peu à Markdown, mais pas entièrement. Ainsi, il devient encore un autre format à apprendre. SHFB fait actuellement le travail, mais ce n'est pas une expérience agréable. Quelque chose vaut mieux que rien et EWoodruff a mes remerciements éternels pour avoir gardé cela vivant et mis à jour pendant si longtemps.

Du point de vue d'un développeur .NET, un très bon outil de génération de documentation open source pour .NET est toujours nécessaire/recherché. À mon avis, c'est de préférence un outil qui permet d'écrire du texte long avec Markdown parce que c'est quelque chose de connu et agréable à utiliser.

Je sais que les équipes MS veulent probablement mettre en place quelque chose pour expédier asp.net 5, mais cela touche une douleur de longue date que les développeurs ressentent.

Une de mes suggestions est de travailler avec http://commonmark.org/ pour développer des modules commonmark et d'envisager d'améliorer quelque chose comme https://github.com/Knagis/CommonMark.NET.

Sinon, soyez au moins ouvert au remplacement du système de documentation après la première version afin que la communauté ne soit pas coincée avec quelque chose qui a beaucoup de frictions à utiliser... encore une fois.

Aussi un autre point douloureux. Les documents doivent être disponibles dans un format pouvant être utilisé localement. Il y a des gens qui travaillent sur des systèmes qui ne sont pas connectés à Internet et la documentation hors ligne est une bouée de sauvetage. J'ai dû travailler dans de tels environnements et les documentations hors ligne sont inestimables.

@ryanbnl Nous recherchons une solution pour la documentation de référence de l'API et le contenu conceptuel.

@michaelherndon Je suis tout à fait d'accord sur le besoin d'un bon outil de génération de documents open source pour .NET ! Vous avez également raison de dire que nous avons besoin de mettre quelque chose en place rapidement pour ASP.NET. Si une documentation basée sur .NET prise en charge par la communauté devait émerger, nous serions bien sûr disposés à l'adopter. Nous convenons également que le fait d'avoir un moyen d'accéder à la documentation hors ligne est une exigence.

D'accord, c'est clair :) Pour les documents API, cela vaut la peine de regarder doxygen. Il est vraiment puissant et peut générer des diagrammes de classes (ce qui peut être inestimable dans certaines situations). J'ai fait une comparaison détaillée de doxygen/sandcastle l'année dernière, je peux vous envoyer une copie si cela peut aider ? Il contient de nombreux exemples + un guide d'installation étape par étape (doxygen est difficile à installer) ;)

Il semble qu'un problème soit de garder la documentation open source afin que d'autres puissent y contribuer. Deuxièmement, l'outil utilisé pour produire et maintenir une telle documentation.
Ne pouvons-nous pas avoir un outil qui est open source et qui permet de générer du HTML/GHMD pour le téléchargement final. Toute personne ayant besoin de contribuer peut utiliser cet outil et modifier les pages en fonction de son niveau d'accès sur github. L'outil doit être flexible afin qu'il puisse être utilisé pour de petits ou grands projets. Cet outil peut être une extension VS qui génère de la documentation pour n'importe quel projet et des exemples de documentation pour les modèles de base peuvent être facultatifs, comme les options d'authentification actuelles dans les nouveaux projets.

@farrukhsubhani l'outil ne devrait probablement pas dépendre de VS : si nous voulons que les utilisateurs Mac et Linux utilisent et contribuent à ASP.NET, l'outil doit être multiplateforme et ne devrait pas nécessiter une installation massive.

Je remarque qu'il y a très peu de commentaires de documentation dans les sources maintenant. bien que cela varie d'un fichier à l'autre. Y a-t-il eu une décision sur l'utilisation de cela comme entrée pour les documents de référence, ou cela a-t-il appartenu à des développeurs individuels ?

Quoi que donne cette discussion, je voudrais parler en faveur d'avoir au moins cela à l'avenir, avec la prise en charge du compilateur pour créer ces fichiers XML (ou un autre format qui se branche sur IntelliSense) et l'expérience d'édition et de mise en évidence d'aujourd'hui qui est particulièrement mignonne avec Roslyn dans Visual Studio.

Peut-être que d'autres sont violemment en désaccord, mais je n'aime pas particulièrement éditer les commentaires de style /* */ pour cela et les séries de * alignés. S'il vous plaît, dites-moi que je n'ai pas à m'inquiéter ;)

@danroth27

Juste quelques réflexions et merci d'avance d'avoir au moins lu et réfléchi à cela.

Le texte restructuré ressemble à PITA pour injecter des choses simples comme un lien ou un en-tête. Je prendrais des commentaires de code Javadoc ou juste du html vanille dessus n'importe quel jour de la semaine.

============
h1
============

***************
h2
***************

h3
------------------

check out the _aspnet homepage.

.. _aspet: http://www.aspnet.com/

J'aimerais demander que l'aspnet discute en interne de la collaboration avec la communauté pour définir des objectifs / spes sur un outil de documentation .net et peut-être fournir des incitations créatives comme la reconnaissance ou quelque chose du genre. Je vous demande également à tous de discuter de la mise en place du projet via la fondation .NET. Cela pourrait également servir de stagiaire décent / projet d'été de code sur lequel les étudiants en cs pourraient travailler, car cela impliquerait très probablement la création d'un analyseur.

Cela ne s'adresse pas à vous ou à quelqu'un en particulier, mais il est tard dans les cycles de développement pour commencer à publier et à réfléchir à ce sujet car cela vous oblige à utiliser quelque chose qui fonctionne, mais ce n'est pas quelque chose qui frappe tous les scénarios, y compris une faible barrière à l'entrée.

Hypothétiquement parlant, converser avec la communauté plus tôt aurait peut-être au moins produit un outil qui aurait été utilisable et qui aurait pu être construit en parallèle au-dessus de tout le travail acharné de l'équipe aspnet comme bon exemple d'un aspnet dogfooding 5.

Cela étant dit, si cela a été lancé maintenant, il pourrait être prêt à être utilisé par exemple .NET core 5.

@ericwj toutes les API publiques doivent ¹ avoir des commentaires de documentation XML dessus. Cependant, au début du projet, nous avons assoupli cette exigence, car écrire de nombreux documents sur les API dont nous savions qu'ils changeraient de manière significative était considéré comme un effort largement inutile. Cependant, dans tous les commits des derniers mois, il devrait y avoir une quantité importante de documentation présente. Il y a en effet encore beaucoup de trous, mais c'est une obligation de l'équipe de fournir cette documentation. Lors de la mise à jour de la documentation, nous avons tendance à nous concentrer sur les API les plus importantes auxquelles nous pensons que les développeurs auront accès, et à reléguer les API plus ésotériques à un statut moins documenté (que nous espérons toujours remplir un jour).

¹ _adjectif_ requis

Quelque chose qui n'est pas facultatif.
Peut également signifier quelque chose qui _est_ facultatif dans le contexte des commentaires de documentation XML.

@michaelherndon BTW ce projet fait déjà partie de la Fondation .NET .

@Eilon , le contexte parlait d'ajouter un outil de documentation .net, pas aspnet 5.

@michaelherndon ah j'ai compris, merci !

@shanselman @danroth27 , j'ai informé vendredi dernier mon responsable et celui-ci a contacté les PM du groupe principal MSDN à propos de ce fil. Ils devraient vous contacter au sujet de votre problème de documentation. Bonne journée.

@michaelherndon Je suis d'accord que la syntaxe de l'en-tête est un peu plus détaillée. Un autre cas général est le lien vers une fonction ou une page de la documentation, où RST brille :

More Info
=========

This function wraps :func:`bar`, 
more info in :doc:`bar-like-functions` or on our `website <http://www.aspnet.com>`_.

Faire quelque chose de similaire dans Markdown :

### More Info

This function wraps [bar](func:bar), 
more info in [Bar Like Functions](bar-like-functions.md) or on our [website](http://www.aspnet.com).

Je ne vois pas une grande différence fondamentale ici. RST avec Sphinx vous offre un large éventail de fonctionnalités de référence précieuses qui seraient perdues ou liées de manière non sémantique à une URL ou à un document HTML dans le cas de Markdown.

Une autre friandise intéressante dans ce sens est ce document sur la façon d'écrire RST et MD de manière compatible : https://gist.github.com/dupuy/1855764. Markdown prend généralement en charge les en-têtes de style RST, de sorte que le style d'en-tête fonctionne sur les deux.

Vous pouvez également configurer Sphinx ou d'autres outils pour comprendre la syntaxe de base de Markdown avec une extension s'il s'agit d'un show-stopper.

Je me souviens avoir dit au panel OSS de MVP Submit il y a environ 18 mois qu'il n'y avait pas de bonnes options pour la documentation dans .NET :stuck_out_tongue_closed_eyes :

Ce que j'aimerais vraiment voir, c'est un moyen de générer des démarques ou d'abord plus une table des matières à partir de la documentation XML .NET. Cela peut ensuite être chargé dans quelque chose comme readthedocs ou github wiki.

Sandcastle a déjà une tonne de code pour lire la documentation XML .NET et est extensible avec de nouveaux styles et types de sortie. Vous pourriez vous baser là-dessus.

Comment puis-je regarder ce fil et comprendre quelle était la conclusion, si une décision a été prise, et si oui, quelle était-elle?

https://github.com/aspnet/Docs

Pourquoi n'utilisez-vous pas DocFX ?

Lorsque nous avons commencé à écrire de la documentation pour ASP.NET 5, le projet docfx en était encore aux premiers stades de développement. Sphinx est toujours un cadre de documentation beaucoup plus mature et riche en fonctionnalités. En plus de cela, Read the Docs propose une très belle solution d'hébergement de documentation.

Cela dit, nous soutenons l'effort de docfx en tant que solution de documentation pour .NET et c'est excitant de voir que docfx est maintenant open source ! Nous prévoyons déjà d'utiliser docfx pour la documentation de référence de l'API et nous prévoyons de passer à docfx à mesure qu'il mûrit.

Il semble juste dommage d'aller dans deux directions différentes lorsque docfx semble être ce que MSDN utilise, du moins en se basant sur les thèmes intégrés.

@simonmurdock docfx ne prend pas (encore) en charge la génération de documents hors ligne, tels que PDF

Ouais @cocowalla Je suis dans un flux éternel sur l'état de l'union avec la documentation. J'écris maintenant mes articles dans sphinx, mais il n'y a pas vraiment de moyen agréable de générer des documents d'API intégrés à sphinx.

Le plan actuel est Sphinx pour tous les articles et un site séparé pour la sortie de DocFX, jusqu'à ce que les ApiDocs Sphinx soient un peu plus beaux.

@simonmurdock Voici ce que nous faisons actuellement pour générer des documents de référence d'API pour ASP.NET en utilisant une combinaison de docfx et de l'extension autoapi Sphinx : https://github.com/aspnet/apidocs. C'est encore un peu difficile, mais nous travaillons avec les gens de Read the Docs sur un tas d'améliorations.

@danroth27 Tant de votes étaient pour RsT, cependant, vous avez finalement choisi MD ? Lorsque je clique sur MODIFIER sur n'importe quelle page de https://docs.microsoft.com/en-us/aspnet/core/ , je vois le fichier source MD sur le GitHub.
Alors pourquoi MD ?

Nous utilisions RST et http://readthedocs.com pendant un certain temps pour les documents ASP.NET Core et EF Core, mais récemment Microsoft a construit sa propre infrastructure de documentation à http://docs.microsoft.com , nous sommes donc passés à aligner avec ça. Bien que Markdown ne soit pas un langage de documentation aussi mature que reStructuredText, il est plus familier à un public plus large. Même Read the Docs prend en charge les deux formats pour cette raison.

@ danroth27 Cela signifie-t-il que Microsoft a créé son propre générateur/moteur de documentation non open source qui utilise le démarquage ? Que reste-t-il derrière https://docs.microsoft.com ?

Cela signifie-t-il que Microsoft a créé son propre générateur/moteur de documentation non open source qui utilise le démarquage ?

Non. Le moteur de documentation derrière https://docs.microsoft.com est DocFX et il est construit sur .NET et est entièrement open source. Il utilise le démarquage pour son format.

salut

Je suis peut-être un peu en retard pour poster ça.

Je me demande simplement s'il existe une API, un framework ou un outil qui nous permet de créer un site de documentation comme celui de https://docs.microsoft.com ? Personnellement, j'aime la façon dont la documentation Microsoft est présentée, @ danroth27 a mentionné DocFX qui est le moteur qui a été utilisé, je veux juste savoir si le site lui-même est quelque chose qui est fait à partir de zéro ou s'il existe un modèle ou un package que nous pouvons utiliser pour générer la même apparence ? pas exactement le même mais quelque chose que nous pouvons modifier :)

Merci!
Jude Alquiza.

Plus je lis sur DocFx , plus je l'aime - je vais bientôt l'essayer.

Comment pouvons-nous créer notre propre site Web de documentation comme https://docs.microsoft.com/ en interne sans réinventer la roue ? Nous utilisons un readthedocs hébergé pour les docs python et un doxygen hébergé pour les docs c/c++.

Quelle est la meilleure façon de rassembler tous les documents de l'API sous un même toit ? À la lecture de ce fil, il semble que de nombreuses personnes utilisent sphinx/readthedocs, mais comment convertissez-vous votre documentation .XML au bon format pour ces outils ?