Aspnetcore: ¿Qué formato debemos usar para la documentación de ASP.NET 5?

http://shfb.codeplex.com

O simplemente hacer algo completamente nuevo.

Un buen preprocesador que genere GH Markdown sería excelente.

+1 para Markdown (o Markdown con sabor a GitHub). Puede carecer de algunas funciones, pero es bastante conocido y muy fácil de aprender y usar. Supongo que puede depender de la decisión final sobre dónde se alojará, ya que mencionaste algunas opciones.

Hola Daniel,
Gracias por tu contribución.
Como desarrollador junior, encuentro que es fácil organizar documentos como títulos en la barra lateral, similar a este http://rustbyexample.com/
(EN MI HUMILDE OPINIÓN)

-1 en hacer algo completamente nuevo.
+1 para trabajar en algo existente y mejorar si es posible.

@danroth27 ¿Puede compartir un poco más de detalles sobre sus necesidades de documentación y qué características de un sistema de documentación maduro necesita?

Creo que decir "usar Markdown" es demasiado simplista.

Markdown es un DSL para HTML. Eso es todo. ¿De verdad dirías "Docs es un problema resuelto, usemos HTML!"

Necesitamos un sistema de documentación real como Sphinx.

• Markdown no puede generar una ToC.
• Markdown no puede enlazar entre temas (tienes que hacer los enlaces manualmente)
• Markdown no puede hacer cosas como compatibilidad con varios idiomas o compatibilidad con varias versiones.

Apoyo Read The Docs de @ericholscher , pero más específicamente Sphinx y reStructuredText.

O use DOxygen y vNext nunca se lanzará;)

¿Qué tal algo similar a Roslyn o AngularJS? http://source.roslyn.codeplex.com/ https://docs.angularjs.org/api

Markdown funciona muy bien para la mayoría de los demás proyectos en GitHub. +1 para rebajas.

@shanselman , ¿enlaces relativos?

Creo que usar Sphinx funcionaría.
@issafram Ejemplos aquí:
http://esfinge-doc.org/
https://docs.python.org/3/tutorial/index.html

@akoeplinger Nos gustaría algo de lo que podamos generar fácilmente una tabla de contenido y vincular fácilmente a través de las páginas. También nos gustaría algo que pueda generar una variedad de formatos de documentos, incluidos HTML, PDF y ePub. Los documentos también deben ser legibles en dispositivos móviles.

@issafram Markdown es excelente cuando sus documentos tienen cien páginas, probablemente menos. ¿Pero miles de páginas y tablas de contenido entrelazadas? ¿Mantener los apéndices actualizados? ¿Vincular documentos ASP.NET y .NET? Será un desastre.

Tenga en cuenta que si desea que esto sea realmente de código abierto y, por lo tanto, algo que fomente la contribución, el sistema debe ser lo más simple posible, sin curva de aprendizaje. Markdown no puede generar una ToC por sí mismo, pero un código relativamente simple puede generar una ToC a partir de Markdown.
En Orchard estamos muy contentos con nuestro sistema, que es Markdown en Github más un sitio de Azure con muy poco código (para la indexación y búsqueda de Lucene, además de la generación de ToC) que se actualiza automáticamente cada vez que se envía el repositorio. Herramientas súper simples y familiares.
Lo único que no me gusta es la falta de metadatos (extraemos los títulos de los nombres de los archivos), pero también hay soluciones para eso, como los encabezados YAML de Jeckyll (compatibles con Github) o mi propio formato Snippable.

@issafram Eso no funciona bien en grandes bases de código con MUCHOS documentos y refactorización, por ejemplo. Renombra una clase y _adiós_ enlaces relativos.

_edit_: llego tarde al juego :P

Me alegra saber que la documentación de ASP.NET tendrá miles de páginas ;) Aún así, KISS.

@bleroy Eche un vistazo a este http://read-the-docs.readthedocs.org/en/latest/ y el rST que lo hizo. https://github.com/rtfd/readthedocs.org/blob/master/docs/index.rst

Claro, eso es genial. Solo dando nuestra experiencia. Entiendo que estás en una escala diferente.

rST es la mejor opción aquí, manos a la obra. Al ser ASP.NET, tener algo que sea lo suficientemente inteligente como para actualizar sus índices (desde un ToC o incluso desde el punto de vista de una lista de clases) es probablemente una prioridad principal.

Idealmente, ejecutaría algo en el flujo de trabajo de compilación para capturar todos esos archivos .XML generados a partir de los binarios y luego pasarlos por un procesador para generar los archivos que luego se publican en un servidor. Las herramientas exactas... No tengo ni idea. Muchos han sido mencionados. Recomendaría construir uno propio y de código abierto. Sí, sí... Debate entre construir y comprar, pero detesto usar herramientas que tienen recursos no administrados, como algunas de las anteriores. De todos modos, eso suena ideal... Probablemente tengas limitaciones de presupuesto y tiempo y otras cosas.

@issafram Si todos terminan usando Sphinx/RTD, algo similar a Breathe podría ser un enfoque viable: http://breathe.readthedocs.org/en/latest/ -- es la integración con Sphinx & Doxygen que usa el Archivos XML de Doxygen.

@issafram Me parece que estás describiendo SHFB ... (En realidad, Sandcastle , SHFB simplemente lo hace más placentero de usar: P)

Sí, necesita un preprocesador/postprocesador, puede vincular la relatividad dentro del documento con GHMD para TOC. Para nuestros proyectos, implementamos el nuestro básicamente tomando .Net doc XML y basado en convenciones combinado con código de muestra y otro contenido estático escrito en MD. El resultado final es HTML.

Tener código y contenido editorial estático en MD facilitaría las relaciones públicas. Lo que me gusta de Markdown como formato de fuente es que es mucho más limpio que HTML, XML, etc. Hace que la auditoría sea fácil y adecuada para el control de fuente.

Necesitamos una herramienta de documentación limpia y simple basada en convenciones para .Net, no he encontrado ninguna, si la hay, me encantaría estar informado. Y estaría feliz de contribuir a eso.

En cuanto a la mantenibilidad y la vinculación entre proyectos. Intersphinx es una forma poderosa de hacerlo de manera semántica. Le permite catalogar todas las referencias (ya sean en código o en prosa) y vincularlas explícitamente entre proyectos.

Documentos aquí: http://sphinx-doc.org/latest/ext/intersphinx.html

Este es el tipo de funcionalidad que algo como Markdown no tiene de ninguna manera que yo sepa.

De acuerdo en que el descuento no es la mejor solución, pero por ahora necesitamos una solución simple. Vamos, somos desarrolladores, por lo que podemos extender esto si es necesario. Github admite rebajas, VSO ahora admite rebajas desde la vista de código. ¿Realmente necesitamos un debate? Lo siento si soy demasiado directo.

Rebaja +1

@ctsni Lo admito, Markdown _se sintió_ como la mejor opción a primera vista/pensamiento. Pero cuanto más lo pienso, más se siente como si estuviéramos tratando de clavar una clavija cuadrada en un agujero redondo.

Es cierto que no tengo una buena alternativa, así que me disculpo por no haber contribuido mucho, pero incluso al extender Markdown no _siento_ que terminaríamos con algo tan bonito, limpio y ordenado como Markdown como lo tenemos ahora _dado el requisitos_.

¿Parece que desea replicar la documentación existente de MSDN en un formato de código abierto? ¿Es eso justo? ¿Necesita una solución para manejar descripciones generales, tutoriales, ejemplos de código y documentación de API? ¿O es un subconjunto de eso?

No estoy convencido de que haya una solución, más una colección de herramientas cuya salida se puede combinar. Puedo ver lo que está haciendo ReadTheDocs: reunir múltiples fuentes en un conjunto coherente de documentación. Entonces, Markdown es una respuesta válida a parte de la solución (es decir, las descripciones y los tutoriales), pero ¿no es la imagen completa?

Pregunta abierta: ¿Es posible extraer apéndices y TOC directamente desde Markdown? no me parece muy dificil? Soy parcial. No he trabajado en un sistema con miles de páginas... Lo siento @shanselman , realmente no puedo aportar sabiduría más allá de lo que sé.

@crainicol Cualquier cosa menos que la documentación actual de MSDN sería, para mí, una gran decepción. Siempre les digo a todos que parte de la mejor documentación (en estructura, redacción y todo lo relacionado) se encuentra en MSDN. He visto mucha documentación, pero la mayoría, si no toda, ni siquiera se acerca a la "calidad de MSDN" (en mi humilde opinión, por supuesto). Habiendo dicho eso: un factor importante es, por supuesto, la gente detrás de los documentos de MSDN cuidando tan bien el _contenido_ real de MSDN; la estructura, el diseño, el diseño y todo lo demás viene en segundo lugar.

Tal vez tangencial, pero sería muy bueno tener algo como dash . El desarrollo web evoluciona tan rápido y las nuevas tecnologías se influyen entre sí que me encuentro buscando información en Google aquí y allá. Ser capaz de acceder a todo en un solo lugar contenido que se puede invocar a través de algunas pulsaciones de teclas es increíblemente útil. Hay un esfuerzo similar http://zealdocs.org/ para Linux y Windows.

@crainicol De acuerdo, el objetivo es tener documentos de calidad de MSDN que sean de código abierto y más fáciles de mantener y actualizar.

@ciriarte Hay soporte para traducir documentos de Sphinx a Dash: https://pypi.python.org/pypi/doc2dash -- Hemos analizado la creación automática de conjuntos de Dash en RTD.org, pero actualmente no la tenemos implementada.

Creo que @shanselman lo expresó mejor arriba: Markdown no es la respuesta más de lo que HTML, Word o .txt serían la respuesta. Markdown es principalmente una descripción de presentación: lo que se necesita es algo para generar Markdown (o HTML, documento de Word, archivo .txt, etc.)

Supongo que mi pregunta sería ¿de dónde ven ese contenido? ¿Va a ser escrito a mano? ¿Generado automáticamente a partir del código? ¿Incrustado en los comentarios?

Estoy de acuerdo con @crainicol en una colección de herramientas para fusionar contenido generado automáticamente con páginas "estáticas" de GH Markdown para muestras creadas por el hombre y contenido editorial que no está disponible en XML ensamblado. El resultado podría ser html estático en GHPages, PDF o lo que sea.
El preprocesador podría detectar cualquier contenido estático huérfano si el código cambia de nombre/refactoriza, es decir
El soporte de idioma podría ser básicamente carpetas opcionales con la misma estructura que neutral. Los documentos no traducidos podrían volver a neutral o pasar, por ejemplo, a Bing translate.

Mirando hacia atrás en la sugerencia original estaría de acuerdo con @ danroth27 en la reducción de formato y readthedocs para compilación. Gracias.

La flexibilidad de readthedocs.org + Sphinx puede permitir la equivalencia con MSDN, si no es accesible.

@ciriarte Eso probablemente también podría admitirse con archivos exportables para el lector de MSDN.

@jalcine @ericholscher suena fantástico.

@RobThree Espero que se pueda persuadir al equipo que actualmente mantiene los documentos para que cambien al nuevo formato; de lo contrario, no vale la pena realizar este ejercicio.

@ctsni es posible: he escrito un analizador de ToC de descuento en python, que toma una lista de archivos y genera un ToC. La parte complicada es anotar los archivos fuente para que el analizador sepa qué extraer para generar la ToC y los apéndices. El formato intermedio, ya sea Markdown o rST, es irrelevante, la clave es obtener los metadatos correctos.

Mirando los documentos de MSDN, las dos piezas clave de metadatos que más importan para los hipervínculos son los enlaces API, para permitir el recorrido del código, y los enlaces conceptuales (por ejemplo, Seguridad) que crean un tema para abarcar la API, los tutoriales, y la información de la arquitectura. Si la parte de la API se hace bien, estoy seguro de que el resto del contenido se puede adaptar a su gusto. Me gusta la idea de Dash, pero creo que ReadTheDocs y Sphinx son lo más cercano que he visto a lo que me gusta de MSDN, pero creo que necesitarán adaptarse para manejar la rica estructura de temas y tutoriales que tiene MSDN.

Me pregunto acerca de todo este concepto. Quiero decir, me encanta la idea de abrir la cadena de documentación e involucrar a la comunidad, pero hacerlo fuera de MSDN me pone los pelos de punta. Desde lo que parece (y puede haber sido) el comienzo de .NET, hemos ido a MSDN para obtener referencias canónicas en cualquier API de Microsoft. Desde WinForms hasta WebForms, todo está en un solo lugar, con buenas referencias cruzadas y formato consistente. No puedo evitar preguntarme si lo que se gana con este esfuerzo proporcionará suficiente beneficio para compensar la fragmentación y la pérdida de consistencia. No digo que no valdrá la pena, y presumiblemente estas discusiones ya han tenido lugar, pero es motivo de reflexión.

+1 para Esfinge

Realmente me gustan el formato y las herramientas de readthedocs y funcionan muy bien para muchos proyectos. No reinventes la rueda. La rebaja está bien. Creo que si no puedes describirlo con Markdown, entonces estás tratando de hacer algo demasiado complicado. Por mi parte, estaría feliz de contribuir si el formato y el nivel de fricción son bajos. El wiki de MSDN estaba llegando allí, pero la mayor parte se cerró y se convirtió en un páramo yermo de contenido antiguo. La comunidad de PHP parece estar haciéndolo bastante bien con su sistema de documentación (aunque sus comentarios a veces se pierden). Creo que mantenerlo simple con Markdown funcionará, pero probablemente sea necesario algún tipo de herramienta de indexación/generación para el "documento maestro" o algo para unirlo y mantenerlo sincronizado. Casi como un sistema de creación de dependencias para miles de fragmentos/documentos de descuento.

Creo que Markdown para fragmentos de texto. Yaml front-matter o archivos json para metadatos. Procesador personalizado basado en .NET con modelo de complemento extensible para agregar fácilmente sintaxis para cosas sofisticadas como TOC y tablas, etc. O simplemente use rst, lo suficientemente similar a Markdown.

Simplemente haga que MSDN sea de código abierto. A menos que sea un desastre :)

@somedave no sé sobre usted, pero me resulta cada vez más difícil encontrar contenido en MSDN, especialmente documentación arquitectónica de alto nivel en marcos no actuales. Tener la documentación vinculada al código y todo el código abierto disponible y bajo control de versiones es una gran mejora.

¿Realmente queremos otro MDSN del nuevo Microsoft? Gran parte de la documentación generada es una pérdida de tiempo. Lo que necesitaba era narrativa y ejemplos, pero a menudo falta esto, dejando solo información básica que ya tengo del sistema de tipos. Con un fácil acceso a la fuente, ahora podemos descubrir qué es lo que realmente hace algo de todos modos. Los artículos, explicaciones y ejemplos de prueba de uso son mucho mejores, especialmente si se crean en respuesta a la demanda, por ejemplo, preguntas de desbordamiento de pila.

@ danroth27 , ¿está hablando únicamente de documentación javadoc/xmldoc, o también de documentación en general? Es decir, este 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

Definitivamente HTML pero con la capacidad de usarlo localmente, digamos instalarlo en el IIS local (o simplemente localmente).

Construya sobre la canalización de Sandcastle y SHFB y ayude a hacerlo más agradable (más simple y 'amigable con el código abierto'). Se puede agregar soporte para creación de rebajas (para contenido conceptual) y renderizado (ya se han hecho algunos comienzos en esta dirección).
Hay mucho valor dogfood en el soporte de las populares herramientas basadas en .NET (medio millón de descargas para SHFB). Los modismos se filtran de las herramientas al proyecto mismo. Por ejemplo, con .NET es realmente valioso admitir fragmentos de código en varios idiomas, de modo que VB.NET y F# puedan mantenerse como lenguajes viables en la plataforma. Sandcastle y la salida estilo MSDN hacen esto muy bien.

El problema con reStructuredText es que es algo así como Markdown, pero no del todo. Así se convierte en un formato más para aprender. SHFB actualmente hace el trabajo, pero no es una experiencia agradable. Algo es mejor que nada y EWoodruff tiene mi eterno agradecimiento por mantener esto vivo y actualizado durante tanto tiempo.

Desde el punto de vista de un desarrollador de .NET, todavía se necesita/se busca una herramienta de generación de documentos de código abierto realmente buena para .NET. En mi opinión, es preferible una herramienta que permita escribir texto de formato largo con Markdown porque es algo conocido y agradable de usar.

Sé que los equipos de MS probablemente quieran poner en marcha algo para enviar asp.net 5 por la puerta, pero esto toca un dolor de larga data que sienten los desarrolladores.

Una de mis sugerencias es trabajar con http://commonmark.org/ para desarrollar módulos commonmark y buscar mejorar algo como https://github.com/Knagis/CommonMark.NET.

De lo contrario, al menos esté abierto a reemplazar el sistema de documentos después del primer lanzamiento para que la comunidad no se quede atrapada con algo que tiene mucha fricción para usar... otra vez.

También otro punto de dolor. Los documentos deben estar disponibles en algún formato que se pueda usar localmente. Hay personas que trabajan en sistemas que no están conectados a Internet y la documentación fuera de línea es un salvavidas. Tuve que trabajar en tales entornos y la documentación fuera de línea es invaluable.

@ryanbnl Estamos buscando una solución tanto para la documentación de referencia de la API como para el contenido conceptual.

@michaelherndon Estoy completamente de acuerdo en que se necesita una buena herramienta de generación de documentos de código abierto para .NET. También tiene razón en que tenemos la necesidad de poner en marcha algo rápidamente para ASP.NET. Si surgiera una documentación basada en .NET compatible con la comunidad, por supuesto estaríamos abiertos a adoptarla. También estamos de acuerdo en que tener una forma de acceder a la documentación fuera de línea es un requisito.

De acuerdo, eso está claro :) Para los documentos API, vale la pena mirar doxygen. Es realmente poderoso y puede generar diagramas de clase (que pueden ser invaluables en ciertas situaciones). Hice una comparación detallada de doxygen/sandcastle el año pasado, puedo enviarle una copia si le sirve de ayuda. Contiene muchos ejemplos + una guía de instalación paso a paso (doxygen es difícil de instalar) ;)

Parece que un problema es mantener la documentación de código abierto para que otros puedan contribuir. El segundo es la herramienta utilizada para producir y mantener dicha documentación.
¿No podemos tener una herramienta que sea de código abierto y permita generar html/GHMD para la carga final? Cualquiera que necesite contribuir puede usar esta herramienta y modificar páginas según su nivel de acceso en github. La herramienta debe ser flexible para que pueda usarse en proyectos pequeños o grandes. Esta herramienta puede ser una extensión VS que genera documentación para cualquier proyecto y la documentación de muestra para plantillas básicas puede ser opcional, como las opciones de autenticación actuales en nuevos proyectos.

@farrukhsubhani , la herramienta probablemente no debería depender de VS: si queremos que los usuarios de Mac y Linux usen y contribuyan a ASP.NET, la herramienta debe ser multiplataforma y no debería requerir una gran instalación.

Me doy cuenta de que ahora hay muy pocos comentarios de documentación en las fuentes. aunque varía de un archivo a otro. ¿Ha habido una decisión sobre usar eso como entrada para los documentos de referencia, o ha dependido de los desarrolladores individuales?

Cualquiera que sea el resultado de esta discusión, me gustaría hablar a favor de al menos tener eso en el futuro, con soporte de compilador para crear esos archivos XML (u otro formato que se conecta a IntelliSense) y la experiencia actual de edición y resaltado que es particularmente linda con Roslyn en Visual Studio.

Tal vez otros discrepen violentamente, pero particularmente no me gusta editar comentarios de estilo /* */ para eso y series de * alineados. Por favor, dime que no debo preocuparme ;)

@danroth27

Solo algunos pensamientos y gracias de antemano por al menos leer y pensar en esto.

El texto reestructurado parece PITA para inyectar cosas simples como un enlace o un encabezado. Tomaría comentarios de código Javadoc o simplemente html vainilla sobre esto cualquier día de la semana.

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

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

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

check out the _aspnet homepage.

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

Me gustaría solicitar que aspnet discuta internamente el trabajo con la comunidad para establecer algunos objetivos/especialidades en una herramienta de documentación de .net y tal vez proporcione algunos incentivos creativos como reconocimiento o algo por el estilo. También les pido que discutan la configuración del proyecto a través de la fundación .NET. Esto también podría servir como un pasante / verano decente de código como proyecto para que los estudiantes de cs trabajen en él, ya que lo más probable es que implique la creación de un analizador.

Esto no está dirigido a usted ni a nadie en particular, pero es tarde en los ciclos de desarrollo para comenzar a publicar y pensar en esto, ya que los obliga a arrinconarse para usar algo que funciona, pero no es algo que golpea todos los escenarios, incluida la baja barrera de entrada.

Hablando hipotéticamente, la conversación anterior con la comunidad puede haber producido al menos una herramienta ahora que habría sido utilizable y podría haberse construido en paralelo además del arduo trabajo del equipo de aspnet como un buen ejemplo de una aspnet 5 de dogfooding.

Dicho esto, si esto se inició ahora, podría estar listo para usar, por ejemplo, .NET core 5.

@ericwj se requiere que todas las API públicas ¹ tengan comentarios de documentos XML en ellas. Sin embargo, al principio del proyecto relajamos ese requisito porque escribir muchos documentos sobre API que sabíamos que cambiarían significativamente se consideró en gran medida un esfuerzo inútil. Sin embargo, en todas las confirmaciones de los últimos meses debe haber una cantidad significativa de documentación presente. De hecho, todavía hay muchos agujeros, pero es una obligación del equipo proporcionar esta documentación. Cuando revisamos los documentos, tendemos a centrarnos en las API más importantes a las que creemos que accederán los desarrolladores, y relegamos las API más esotéricas a un estado menos documentado (que aún esperamos completar algún día).

¹ _adjetivo_ requerido

Algo que no es opcional.
También puede significar algo que _es_ opcional en el contexto de los comentarios de documentos XML.

@michaelherndon Por cierto, este proyecto ya es parte de la Fundación .NET .

@Eilon, el contexto hablaba de agregar una herramienta de documentación .net, no aspnet 5.

@michaelherndon ah entendido, gracias!

@shanselman @danroth27 , le informé el viernes pasado a mi gerente y este se comunicó con los PM del grupo principal de MSDN sobre ese hilo. Deben contactarlo sobre su asunto de documentación. Que tenga un lindo día.

@michaelherndon Estoy de acuerdo en que la sintaxis del encabezado es un poco más detallada. Otro caso general es vincular a una función o página en la documentación, que es donde brilla RST:

More Info
=========

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

Haciendo algo similar en 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).

No veo una gran diferencia fundamental aquí. RST con Sphinx le brinda una gran variedad de funciones de referencia valiosas que se perderían o se vincularían de forma no semántica a una URL o documento HTML en el caso de Markdown.

Otro dato interesante en este sentido es este documento sobre cómo escribir RST y MD de forma compatible: https://gist.github.com/dupuy/1855764. Markdown generalmente admite encabezados de estilo RST, por lo que el estilo de encabezado funcionaría en ambos.

También puede configurar Sphinx u otras herramientas para comprender la sintaxis básica de Markdown con una extensión si es un obstáculo.

Recuerdo haber dicho en el panel de OSS en MVP Submit hace unos 18 meses que no había buenas opciones para la documentación en .NET :stuck_out_tongue_closed_eyes:

Lo que realmente me gustaría ver es una forma de generar Markdown o rst más una tabla de contenido a partir de la documentación XML de .NET. Eso se puede cargar en algo como readthedocs o github wiki.

Sandcastle ya tiene un montón de código para leer la documentación XML de .NET y es extensible con nuevos estilos y tipos de salida. Podrías construir sobre eso.

¿Cómo miro este hilo y averiguo cuál fue la conclusión, si se tomó una decisión y, de ser así, cuál fue?

https://github.com/aspnet/Docs

¿Por qué no están usando DocFX?

Cuando comenzamos a escribir documentación para ASP.NET 5, el proyecto docfx aún estaba en las primeras etapas de desarrollo. Sphinx sigue siendo un marco de documentación mucho más maduro y rico en funciones. Además de eso, Read the Docs ofrece una solución de alojamiento de documentación realmente agradable.

Dicho esto, apoyamos el esfuerzo de docfx como una solución de documentación para .NET y es emocionante ver que docfx ahora es de código abierto. Ya estamos planeando usar docfx para la documentación de referencia de la API y esperamos pasar a docfx a medida que madure.

Simplemente parece una pena ir en dos direcciones diferentes desde el principio cuando docfx parece ser lo que está usando MSDN, al menos siguiendo los temas integrados.

@simonmurdock docfx (todavía) no admite la generación de documentos sin conexión, como PDF

Sí, @cocowalla , estoy en constante cambio sobre el estado de la unión con la documentación. Ahora estoy escribiendo mis artículos en sphinx, pero no hay una forma realmente agradable de generar documentos API integrados en sphinx.

El plan actual es Sphinx para todos los artículos y un sitio separado para la salida de DocFX, hasta que Sphinx ApiDocs se vea un poco mejor.

@simonmurdock Esto es lo que hacemos actualmente para generar documentos de referencia de API para ASP.NET usando una combinación de docfx y la extensión Sphinx autoapi : https://github.com/aspnet/apidocs. Todavía es un poco difícil, pero estamos trabajando con la gente de Read the Docs en un montón de mejoras.

@ danroth27 Tantos votos fueron para RsT, sin embargo, ¿finalmente seleccionó MD? Cuando hago clic en EDITAR en cualquier página de https://docs.microsoft.com/en-us/aspnet/core/ , veo el archivo fuente de MD en GitHub.
Entonces, ¿por qué MD?

Usábamos RST y http://readthedocs.com durante un tiempo para los documentos de ASP.NET Core y EF Core, pero recientemente Microsoft creó su propia infraestructura de documentos en http://docs.microsoft.com , por lo que nos mudamos a alinear con eso. Si bien Markdown no es un lenguaje de documentación tan maduro como reStructuredText, es más familiar para una audiencia más amplia. Incluso Read the Docs admite ambos formatos por este motivo.

@ danroth27 ¿Significa que Microsoft ha creado su propio motor/generador de documentación de código no abierto que usa rebajas? ¿Qué queda detrás de https://docs.microsoft.com?

¿Significa que Microsoft ha creado su propio motor/generador de documentación de fuente no abierta que usa rebajas?

No. El motor de documentos detrás de https://docs.microsoft.com es DocFX , se basa en .NET y es completamente de código abierto. Utiliza Markdown para su formato.

Hola

Puede que tarde un poco en publicar esto.

Me pregunto si existe una API, un marco o una herramienta que nos permita crear un sitio de documentación como el de https://docs.microsoft.com. Personalmente, me gusta cómo se presenta la documentación de Microsoft, @danroth27 mencionó DocFX, que es el motor que se usó, solo quiero saber si el sitio en sí es algo que se hace desde cero o si hay una plantilla o paquete que podamos utilizar para generar la misma apariencia? no exactamente lo mismo pero algo que podemos modificar :)

¡Gracias!
Jude Alquiza.

Cuanto más leo sobre DocFx , más me gusta. Lo probaré pronto.

¿Cómo podemos crear nuestro propio sitio web de documentación como https://docs.microsoft.com/ internamente sin reinventar la rueda? Usamos un readthedocs alojado para documentos de python y un doxygen alojado para documentos de c/c++.

¿Cuál es la mejor manera de tener todos los documentos de la API bajo un mismo techo? Al leer este hilo, parece que muchas personas usan sphinx/readthedocs, pero ¿cómo está convirtiendo su documentación .XML al formato correcto para estas herramientas?