Aspnetcore: Que formato devemos usar para a documentação do ASP.NET 5?

http://shfb.codeplex.com

Ou apenas faça algo novo.

Um bom pré-processador gerando GH Markdown seria excelente.

+1 para Markdown (ou Markdown com sabor do GitHub). Pode faltar alguns recursos, mas é bastante conhecido e muito fácil de aprender e usar. Eu acho que pode depender da decisão final sobre onde ele será hospedado, como você mencionou algumas opções.

Ola daniel,
Obrigado por sua contribuição.
Como desenvolvedor júnior, acho fácil organizar documentos como títulos na barra lateral, semelhante a este http://rustbyexample.com/
(NA MINHA HUMILDE OPINIÃO)

-1 em fazer algo novo.
+1 para trabalhar em algo existente e aprimorar, se possível.

@danroth27 Você pode compartilhar um pouco mais de detalhes sobre suas necessidades de documentação e quais recursos de um sistema de documentação maduro você precisa?

Acho que dizer "usar Markdown" é muito simplista.

Markdown é uma DSL para HTML. Isso é tudo. Você realmente diria "Documentos é um problema resolvido, vamos usar HTML!"

Precisamos de um sistema de documentação real como o Sphinx.

• Markdown não pode gerar um ToC.
• Markdown não pode vincular entre tópicos (você precisa fazer os links manualmente)
• O Markdown não pode fazer coisas como suporte a vários idiomas ou suporte a várias versões.

Eu apoio o Read The Docs de @ericholscher , mas mais especificamente Sphinx e reStructuredText.

Ou use DOxygen e o vNext nunca será lançado ;)

Que tal algo semelhante ao Roslyn ou AngularJS? http://source.roslyn.codeplex.com/ https://docs.angularjs.org/api

Markdown funciona muito bem para a maioria dos outros projetos no GitHub. +1 para Markdown.

@shanselman , links relativos?

Acho que usar Sphinx funcionaria.
@issafram Exemplos aqui:
http://sphinx-doc.org/
https://docs.python.org/3/tutorial/index.html

@akoeplinger Gostaríamos de algo que pudéssemos gerar facilmente um sumário e vincular facilmente entre as páginas. Também gostaríamos de algo que possa gerar uma variedade de formatos de documentos, incluindo HTML, PDF e ePub. Os documentos também devem ser legíveis em dispositivos móveis.

@issafram Markdown é ótimo quando seus documentos têm cem páginas, provavelmente menos. Mas milhares de páginas e índices interligados? Manter os apêndices atualizados? Vinculando documentos ASP.NET e .NET? Vai ser uma bagunça.

Tenha em mente que, se você quer que isso seja realmente de código aberto e, portanto, algo que incentive a contribuição, o sistema deve ser o mais simples possível, sem curva de aprendizado. O Markdown não pode gerar um ToC por si só, mas um código relativamente simples pode gerar o ToC a partir do Markdown.
Nós da Orchard estamos muito felizes com nosso sistema, que é o Markdown no Github mais um site do Azure com muito pouco código (para indexação e pesquisa do Lucene, além da geração de ToC) que é atualizado automaticamente toda vez que o repositório é enviado. Ferramentas super simples e familiares.
A única coisa que não gosto é a falta de metadados (extraímos os títulos dos nomes dos arquivos), mas também existem soluções para isso, como os cabeçalhos YAML do Jeckyll (suportados pelo Github) ou meu próprio formato Snippable.

@issafram Isso não funciona bem em bases de código enormes com MUITOS documentos e refatoração, por exemplo. Renomeie uma classe e links relativos _bye bye_.

_edit_: Estou atrasado para o jogo :P

Fico feliz em saber que a documentação do ASP.NET terá milhares de páginas ;) Ainda assim, KISS.

@bleroy Dê uma olhada neste http://read-the-docs.readthedocs.org/en/latest/ e o rST que o fez. https://github.com/rtfd/readthedocs.org/blob/master/docs/index.rst

Claro, isso é ótimo. Apenas dando a nossa experiência. Eu entendo que você está em uma escala diferente.

rST é a melhor opção aqui, mãos à obra. Sendo ASP.NET, ter algo inteligente o suficiente para atualizar seus índices (de um ToC ou mesmo de um ponto de vista de listagem de classes) é provavelmente uma prioridade.

Idealmente, eu executaria algo no Build Workflow para pegar todos os arquivos .XML gerados a partir dos binários e depois colocá-los em um processador para gerar os arquivos que serão publicados em um servidor. As ferramentas exatas... Eu não tenho idéia. Muitos foram mencionados. Eu recomendaria construir o seu próprio e de código aberto. Sim sim... Build vs buy debate, mas eu odeio usar ferramentas que têm recursos não gerenciados, como alguns dos acima. De qualquer forma, isso soa ideal... Você provavelmente tem restrições de orçamento e tempo e tudo mais.

@issafram Se todos acabarem usando Sphinx/RTD, algo como Breathe pode ser uma abordagem viável: http://breathe.readthedocs.org/en/latest/ -- é a integração com Sphinx & Doxygen que usa o Arquivos XML Doxygen.

@issafram Parece-me que você está descrevendo SHFB ... (Na verdade, Sandcastle , SHFB apenas torna mais agradável de usar: P)

Sim, você precisa de um pré-processador/pós-processador, você pode vincular a relatividade no documento com o GHMD para TOC. Para nossos projetos nós rodamos nosso próprio basicamente tomando .Net doc XML e baseado em convenção mesclado com código de amostra e outro conteúdo estático escrito em MD. O resultado final é HTML.

Ter código e conteúdo estático editorial em MD tornaria fácil fazer PRs. O que eu gosto no markdown como formato de origem é que ele é muito mais limpo que HTML, XML etc. Torna a auditoria fácil e adequada para o controle de origem.

Precisamos de uma ferramenta de documentação baseada em convenções limpa e simples para .Net, não encontrei uma, se houver, adoraria ser informado. E ficaria feliz em contribuir para isso.

Quanto à manutenibilidade e vinculação entre projetos. Intersfinge é uma maneira poderosa de fazer isso de maneira semântica. Ele permite catalogar todas as referências (sejam elas código ou prosa) e vinculá-las explicitamente em projetos.

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

Este é o tipo de funcionalidade que algo como o Markdown não tem de nenhuma maneira que eu conheça.

Concordamos que o markdown não é a melhor solução, mas por enquanto precisamos de uma solução simples. Com'on, somos desenvolvedores para que possamos estender isso, se necessário. O Github oferece suporte a markdown, o VSO agora oferece suporte recentemente a markdown da visualização de código. Precisamos mesmo de um debate. Desculpe se fui muito direto.

Remarcação +1

@ctsni eu admito, Markdown _felt_ como a melhor escolha à primeira vista/pensamento. Mas quanto mais eu penso nisso, mais parece que estaríamos tentando martelar um pino quadrado em um buraco redondo.

Reconheço que não tenho uma boa alternativa, então peço desculpas por não contribuir muito, mas mesmo ao estender o Markdown, não _sinto_ que acabaríamos com algo do mesmo Markdown bonito, limpo e organizado que temos agora _dado o requisitos_.

Parece que você deseja replicar a documentação existente do MSDN em um formato de código aberto? Isto é Justo? Você precisa de uma solução para lidar com descrições gerais, tutoriais, amostras de código e documentação de API? Ou é um subconjunto disso?

Não estou convencido de que haja uma solução, mais uma coleção de ferramentas cuja saída pode ser combinada. Posso ver o que o ReadTheDocs está fazendo - reunindo várias fontes em um conjunto coerente de documentação. Então Markdown é uma resposta válida para parte da solução (ou seja, as descrições e tutoriais), mas não é a imagem completa?

Pergunta aberta: É possível extrair apêndices e TOC diretamente do markdown? Não me parece muito difícil? Eu sou tendencioso. Eu não trabalhei em um sistema com milhares de páginas... Desculpe @shanselman , eu realmente não posso contribuir com sabedoria além do que eu sei.

@craignicol Qualquer coisa menos do que a documentação atual do MSDN seria, para mim, uma grande decepção. Eu sempre digo a todos que algumas das melhores documentações (em estrutura, redação e tudo sobre isso) são encontradas no MSDN. Eu vi muita documentação, mas a maioria, se não tudo, não chega nem perto da "qualidade do MSDN" (IMHO, é claro). Dito isto: um grande fator é, é claro, as pessoas por trás dos documentos do MSDN cuidarem tão bem do _conteúdo_ real do MSDN; estrutura, layout, design e o que você tem vem em segundo lugar.

Talvez tangencial, mas seria muito bom ter algo como dash . O desenvolvimento da Web evolui tão rápido e as novas tecnologias influenciam umas às outras que me pego pesquisando informações aqui e ali. Ser capaz de acessar tudo em um único local contido que pode ser invocado por meio de algumas teclas é incrivelmente útil. Há um esforço semelhante http://zealdocs.org/ para Linux e Windows.

@craignicol Concordo, o objetivo é ter documentos de qualidade MSDN que sejam de código aberto e mais fáceis de manter e atualizados.

@ciriarte Há suporte para traduzir documentos do Sphinx para o Dash: https://pypi.python.org/pypi/doc2dash -- Analisamos a criação automática de conjuntos de Dash no RTD.org, mas atualmente não o implantamos.

Acho que @shanselman colocou melhor acima - Markdown não é a resposta mais do que HTML, Word ou .txt seriam a resposta. Markdown é principalmente uma descrição de apresentação - o que é necessário é algo para gerar o Markdown (ou HTML, documento do Word, arquivo .txt, etc.)

Acho que minha pergunta seria de onde você vê esse conteúdo vindo? Vai ser escrito à mão? Gerado automaticamente a partir do código? Incorporado nos comentários?

Eu concordo com @craignicol uma coleção de ferramentas para mesclar conteúdo gerado automaticamente com páginas "estáticas" do GH Markdown para amostras feitas pelo homem e conteúdo editorial não disponível em XML de montagem. O resultado pode ser html estático em GHPages, PDF ou qualquer outra coisa.
O pré-processador pode detectar qualquer conteúdo estático órfão se o código for renomeado/refatorado Ie
O suporte a idiomas pode ser basicamente pastas opcionais com a mesma estrutura neutra. Documentos não traduzidos poderiam então voltar para neutro ou passar por tradução do Bing.

Olhando para trás, a sugestão original concordaria com @danroth27 em markdown para formato e readthedocs para compilação. Obrigado.

A flexibilidade do readthedocs.org + Sphinx pode permitir a equivalência com o MSDN, se não for acessível a ele.

@ciriarte Isso provavelmente poderia ser suportado também com arquivos exportáveis ​​para o leitor MSDN.

@jalcine @ericholscher parece fantástico.

@RobThree Espero que a equipe que atualmente mantém os documentos possa ser persuadida a mudar para o novo formato, caso contrário, não vale a pena fazer este exercício.

@ctsni é possível - escrevi um analisador de ToC de remarcação em python, que pega uma lista de arquivos e gera um ToC. A parte complicada é anotar os arquivos de origem para que o analisador saiba o que extrair para gerar o ToC e apêndices. O formato intermediário, seja Markdown ou rST, é irrelevante, é obter os metadados corretos que é a chave.

Observando os documentos do MSDN, os dois principais metadados que mais importam para o hyperlink são os ganchos da API, para permitir a passagem do código, e os ganchos conceituais (por exemplo, Segurança) que criam um tópico para abranger a API, os tutoriais, e as informações de arquitetura. Se a parte da API for bem feita, tenho certeza de que o restante do conteúdo pode ser adaptado para se adequar. Gosto da ideia do Dash, mas acho que ReadTheDocs e Sphinx são os mais próximos que já vi do que gosto no MSDN, mas acho que eles precisarão ser adaptados para lidar com o tópico rico e a estrutura de tutoriais que o MSDN tem.

Eu me pergunto sobre todo esse conceito. Quer dizer, eu adoro a ideia de abrir o código da cadeia de documentação e envolver a comunidade, mas fazer isso fora do MSDN meio que me dá arrepios. Pelo que parece (e pode ter sido) o início do .NET, fomos ao MSDN para referência canônica em qualquer API da Microsoft. De WinForms a WebForms, tudo em um só lugar, com boas referências cruzadas e formatação consistente. Não posso deixar de me perguntar se o ganho com esse esforço fornecerá benefícios suficientes para superar a fragmentação e a perda de consistência. Não estou dizendo que não valerá totalmente a pena, e presumivelmente essas discussões já aconteceram, mas é algo para pensar.

+1 para Esfinge

Eu realmente gosto do formato e das ferramentas readthedocs e eles funcionam muito bem para muitos projetos. Não reinvente a roda. Markdown é bom. Eu acho que se você não pode descrevê-lo com markdown, então você está tentando fazer algo muito complicado. Eu, pelo menos, ficaria feliz em contribuir se o formato e o nível de atrito forem baixos. O wiki do MSDN estava chegando lá, mas a maior parte foi fechada e se tornou um terreno baldio estéril de conteúdo antigo. A comunidade PHP parece estar fazendo isso muito bem com seu sistema de documentos (embora seus comentários às vezes caiam em buracos de coelho). Acho que mantê-lo simples com markdown funcionará, mas provavelmente precisa haver algum tipo de ferramenta de indexação/geração para o "documento mestre" ou algo para reuni-lo e mantê-lo sincronizado. Quase como um sistema de construção de dependência para milhares de snippets/documentos de markdown.

Acho Markdown para fragmentos de texto. Arquivos yaml front-matter ou json para metadados. Processador personalizado baseado em .NET com modelo de plug-in extensível para adicionar facilmente sintaxe para coisas sofisticadas como TOC e tabelas etc. Ou apenas use rst, semelhante o suficiente ao Markdown.

Basta tornar o MSDN Open Source. A menos que seja uma bagunça :)

@somedave não sei sobre você, mas tenho achado cada vez mais difícil encontrar conteúdo no MSDN, especialmente documentação de arquitetura de alto nível em estruturas não atuais. Ter a documentação vinculada ao código e todo o código aberto disponível e sob controle de versão é uma grande melhoria.

Queremos realmente outro MDSN da nova Microsoft? Grande parte da documentação gerada é perda de tempo. O que precisava é narrativa e exemplos, mas muitas vezes isso está faltando, deixando apenas informações básicas que eu já tenho do sistema de tipos. Com fácil acesso à fonte, agora podemos descobrir o que algo realmente faz de qualquer maneira. Artigos, explicações e exemplos de teste de uso são muito melhores, especialmente se criados em resposta à demanda, por exemplo, perguntas de estouro de pilha.

@danroth27 , você está falando puramente sobre documentação javadoc/xmldoc ou também documentação em geral? Ou seja, 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, mas com a capacidade de usá-lo localmente - digamos para instalá-lo no IIS local (ou apenas localmente).

Por favor, construa o pipeline Sandcastle e SHFB e ajude a torná-lo mais agradável (mais simples e 'amigável ao código aberto'). Suporte para autoria de markdown (para conteúdo conceitual) e renderização pode ser adicionado (algumas partidas já foram feitas nessa direção).
Há muito valor dogfood no suporte às ferramentas baseadas em .NET populares (meio milhão de downloads para SHFB). As expressões idiomáticas vazam das ferramentas para o próprio projeto. Por exemplo, com o .NET é realmente valioso oferecer suporte a trechos de código em vários idiomas, para que VB.NET e F# possam ser mantidos como idiomas viáveis ​​na plataforma. Sandcastle e a saída no estilo MSDN fazem isso muito bem.

O problema com reStructuredText é que é como Markdown, mas não inteiramente. Assim, torna-se mais um formato para aprender. SHFB atualmente faz o trabalho, mas não é uma experiência agradável. Algo é melhor do que nada e EWoodruff tem meus eternos agradecimentos por manter isso vivo e atualizado por tanto tempo.

Do ponto de vista do desenvolvedor .NET, uma ferramenta de geração de documentos de código aberto realmente boa para .NET ainda é necessária / desejada. Na minha opinião é de preferência uma ferramenta que permite escrever textos longos com Markdown porque é algo que é conhecido e agradável de usar.

Eu sei que as equipes do MS provavelmente querem colocar algo em funcionamento para lançar o asp.net 5, mas isso toca em uma dor de longa data que os desenvolvedores sentem.

Uma das minhas sugestões é trabalhar com http://commonmark.org/ para desenvolver módulos commonmark e melhorar algo como https://github.com/Knagis/CommonMark.NET.

Caso contrário, pelo menos esteja aberto a substituir o sistema de documentos após o primeiro lançamento, para que a comunidade não fique presa a algo que tenha muito atrito para usar... novamente.

Também outro ponto de dor. Os documentos devem estar disponíveis em algum formato que possa ser usado localmente. Existem pessoas que trabalham em sistemas que não estão conectados à internet e a documentação offline é um salva-vidas. Eu tive que trabalhar em tais ambientes e as documentações offline são inestimáveis.

@ryanbnl Estamos procurando uma solução para documentação de referência da API e conteúdo conceitual.

@michaelherndon Concordo plenamente que existe a necessidade de uma boa ferramenta de geração de documentos de código aberto para .NET! Você também está certo de que precisamos colocar algo em funcionamento rapidamente para o ASP.NET. Se uma documentação baseada em .NET suportada pela comunidade surgisse, é claro que estaríamos abertos a adotá-la. Também concordamos que ter uma maneira de acessar a documentação offline é um requisito.

Ok, isso é claro :) Para documentos de API vale a pena olhar para doxygen. É realmente poderoso e pode gerar diagramas de classes (que podem ser inestimáveis ​​em certas situações). Fiz uma comparação detalhada de doxygen/sandcastle no ano passado, posso enviar uma cópia se ajudar? Ele contém muitos exemplos + um guia de instalação passo a passo (o doxygen é complicado de instalar) ;)

Parece que um problema é manter a documentação de código aberto para que outros possam contribuir. Em segundo lugar está a ferramenta utilizada para produzir e manter tal documentação.
Não podemos ter uma ferramenta que seja de código aberto e permita a geração de html/GHMD para o upload final. Qualquer pessoa que precise contribuir pode usar esta ferramenta e modificar páginas com base em seu nível de acesso no github. A ferramenta deve ser flexível para que possa ser usada em projetos pequenos ou grandes. Esta ferramenta pode ser uma extensão VS que gera documentação para qualquer projeto e documentação de amostra para modelos básicos pode ser opcional como as opções de autenticação atuais em novos projetos.

@farrukhsubhani a ferramenta provavelmente não deve depender do VS: se quisermos que os usuários de Mac e Linux usem e contribuam com o ASP.NET, as ferramentas devem ser multiplataforma e não devem exigir uma grande instalação.

Estou percebendo que há muito poucos comentários de documentação nas fontes agora. embora varie de arquivo para arquivo. Houve uma decisão sobre usar isso como entrada para os documentos de referência ou dependeu de desenvolvedores individuais?

O que quer que essa discussão produza, eu gostaria de falar a favor de pelo menos ter isso no futuro ainda, com suporte de compilador para criar esses arquivos XML (ou outro formato que se conecte ao IntelliSense) e a experiência de edição e destaque de hoje que é particularmente fofa com Roslyn no Visual Studio.

Talvez outros discordem violentamente, mas eu particularmente não gosto de editar comentários no estilo /* */ para isso e séries de *'s alinhados. Por favor me diga que não preciso me preocupar ;)

@danroth27

Apenas alguns pensamentos e obrigado antecipadamente por pelo menos ler e pensar sobre isso.

O texto reestruturado parece PITA para injetar coisas simples como um link ou título. Eu levaria comentários de código Javadoc ou apenas html vanilla sobre isso em qualquer dia da semana.

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

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

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

check out the _aspnet homepage.

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

Eu gostaria de solicitar que a aspnet discutisse internamente o trabalho com a comunidade na definição de algumas metas/especificações em uma ferramenta de documentação .net e talvez forneça alguns incentivos criativos como reconhecimento ou algo nesse sentido. Também peço a todos que discutam a configuração do projeto por meio da fundação .NET. Isso também pode servir como um estágio decente / verão de código como projeto para os alunos de cs trabalharem, pois provavelmente envolveria a criação de um analisador.

Isso não é direcionado a você ou a alguém em particular, mas é tarde nos ciclos de desenvolvimento para agora começar a postar e pensar nisso, pois força vocês a se encurralar para usar algo que funcione, mas não seja algo que atinja todos os cenários, incluindo baixa barreira à entrada.

Hipoteticamente falando, conversar com a comunidade anteriormente pode ter produzido pelo menos uma ferramenta que poderia ter sido utilizável e poderia ter sido construída em paralelo em cima de todo o trabalho duro da equipe aspnet como um bom exemplo de uma aspnet dogfooding 5.

Dito isto, se isso fosse iniciado agora, poderia estar pronto para usar, digamos, o .NET core 5.

@ericwj todas as APIs públicas são necessárias ¹ para ter comentários de documentos XML nelas. No entanto, no início do projeto, relaxamos esse requisito porque escrever muitos documentos em APIs que sabíamos que mudariam significativamente foi considerado um esforço desperdiçado. No entanto, em todos os commits dos últimos meses deve haver uma quantidade significativa de documentação presente. De fato ainda há muitos buracos, mas é obrigação da equipe fornecer essa documentação. Ao corrigir os documentos, tendemos a nos concentrar nas APIs mais importantes que achamos que os desenvolvedores acessarão e relegamos APIs mais esotéricas a um status menos documentado (que ainda esperamos preencher um dia).

¹ _adjetivo_ obrigatório

Algo que não é opcional.
Também pode significar algo que _é_ opcional no contexto de comentários de documentos XML.

@michaelherndon BTW este projeto já faz parte da .NET Foundation .

@Eilon o contexto estava falando sobre adicionar uma ferramenta de documentação .net, não aspnet 5.

@michaelherndon ah entendi, obrigado!

@shanselman @danroth27 , informei na sexta-feira passada meu gerente e este entrou em contato com os PMs do grupo principal do MSDN sobre esse tópico. Eles devem entrar em contato com você sobre sua questão de documentação. Tenha um bom dia.

@michaelherndon Concordo que a sintaxe do cabeçalho é um pouco mais detalhada. Outro caso geral é vincular a uma função ou página na documentação, que é onde o RST brilha:

More Info
=========

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

Fazendo algo semelhante no 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).

Não vejo uma grande diferença fundamental aqui. O RST com Sphinx oferece uma grande variedade de funcionalidades de referência valiosas que seriam perdidas ou vinculadas de maneira não semântica a um URL ou documento HTML no caso do Markdown.

Outro detalhe interessante nesse sentido é este documento sobre como escrever RST e MD de maneira compatível: https://gist.github.com/dupuy/1855764. O Markdown geralmente suporta cabeçalhos no estilo RST, para que o estilo do cabeçalho funcione em ambos.

Você também pode configurar o Sphinx ou outras ferramentas para entender a sintaxe básica do Markdown com uma extensão se for um impedimento de exibição.

Lembro-me de dizer no painel OSS no MVP Submit cerca de 18 meses atrás que não havia boas opções para documentação em .NET :stuck_out_tongue_closed_eyes:

O que eu realmente gostaria de ver é uma maneira de gerar markdown ou rst plus um índice da documentação .NET XML. Isso pode ser carregado em algo como readthedocs ou github wiki.

O Sandcastle já tem uma tonelada de código para ler a documentação XML do .NET e é extensível com novos estilos e tipos de saída. Você poderia construir sobre isso.

Como eu olho para este tópico e descubro qual foi a conclusão, se uma decisão foi tomada e, em caso afirmativo, qual foi?

https://github.com/aspnet/Docs

Por que vocês não estão usando DocFX?

Quando começamos a escrever a documentação para ASP.NET 5, o projeto docfx ainda estava nos estágios iniciais de desenvolvimento. Sphinx ainda é uma estrutura de documentação muito mais madura e rica em recursos. Além disso, o Read the Docs oferece uma solução de hospedagem de documentação muito boa.

Dito isso, apoiamos o esforço do docfx como uma solução de documentação para .NET e é emocionante ver que o docfx agora é de código aberto! Já estamos planejando usar o docfx para documentação de referência da API e esperamos migrar para o docfx à medida que ele amadurecer.

Parece uma pena seguir duas direções diferentes quando o docfx parece ser o que o MSDN está usando, pelo menos seguindo os temas internos.

@simonmurdock docfx (ainda) não suporta a geração de documentos offline, como PDF

Pois é @cocowalla estou em eterno fluxo sobre o estado da união com documentação. Agora estou escrevendo meus artigos no sphinx, mas não há uma maneira muito legal de gerar documentos de API integrados ao sphinx.

O plano atual é Sphinx para todos os artigos e um site separado para a saída do DocFX, até que o Sphinx ApiDocs pareça um pouco melhor.

@simonmurdock Aqui está o que fazemos atualmente para gerar documentos de referência de API para ASP.NET usando uma combinação de docfx e a extensão Sphinx autoapi : https://github.com/aspnet/apidocs. Ainda é um pouco difícil, mas estamos trabalhando com o pessoal do Read the Docs em várias melhorias.

@danroth27 Tantos votos foram para RsT, no entanto, eventualmente você selecionou MD? Quando clico em EDITAR em qualquer página em https://docs.microsoft.com/en-us/aspnet/core/ , vejo o arquivo de origem MD no GitHub.
Então, por que MD?

Estávamos usando RST e http://readthedocs.com por um tempo para os documentos ASP.NET Core e EF Core, mas recentemente a Microsoft criou sua própria infraestrutura de documentos em http://docs.microsoft.com , então mudamos para alinhar com isso. Embora o markdown não seja uma linguagem de documentação tão madura quanto o reStructuredText, é mais familiar para um público mais amplo. Até o Read the Docs é compatível com os dois formatos por esse motivo.

@danroth27 Isso significa que a Microsoft criou seu próprio gerador/motor de documentação não-open source que usa markdown? O que fica para trás https://docs.microsoft.com?

Isso significa que a Microsoft criou seu próprio gerador/motor de documentação de código não aberto que usa markdown?

Não. O mecanismo de documentação por trás do https://docs.microsoft.com é o DocFX e foi desenvolvido em .NET e é totalmente de código aberto. Ele usa markdown para seu formato.

Oi

Talvez eu demore um pouco para postar isso.

Eu só estou querendo saber se existe uma API ou estrutura ou ferramenta que nos permite criar um site de documentação como o de https://docs.microsoft.com? Eu pessoalmente gosto de como a documentação da microsoft é apresentada, @danroth27 mencionou o DocFX que é o motor que foi usado, eu só quero saber se o site em si é algo que é feito do zero ou existe um modelo ou pacote que podemos usar para gerar a mesma aparência? não exatamente o mesmo, mas algo que podemos modificar :)

Obrigado!
Judas Alquiza.

Quanto mais eu leio sobre DocFx , mais eu estou gostando - vou tentar em breve.

Como podemos criar nosso próprio site de documentação como https://docs.microsoft.com/ internamente sem reinventar a roda? Usamos um readthedocs hospedado para documentos python e um doxygen hospedado para documentos c/c++.

Qual é a melhor maneira de colocar todos os documentos da API sob o mesmo teto? Ao ler este tópico, parece que muitas pessoas usam sphinx/readthedocs, mas como você está convertendo sua documentação .XML para o formato correto para essas ferramentas?