Aspnetcore: Какой формат следует использовать для документации ASP.NET 5?

http://shfb.codeplex.com

Или просто сделать что-то новое.

Хороший препроцессор, генерирующий GH Markdown, был бы превосходен.

+1 для Markdown (или GitHub Flavored Markdown). Возможно, ему не хватает некоторых функций, но он довольно хорошо известен и очень прост в освоении и использовании. Я предполагаю, что это может зависеть от окончательного решения о том, где он будет размещен, поскольку вы упомянули несколько вариантов.

Привет Даниэль,
Спасибо за ваш вклад.
Как младший разработчик, я считаю, что легко организовать документ в виде заголовков на боковой панели, как это http://rustbyexample.com/
(ПО МОЕМУ МНЕНИЮ)

-1 о создании чего-то совершенно нового.
+1, чтобы поработать над чем-то существующим и улучшить, если это возможно.

@ danroth27 Можете ли вы поделиться более подробной информацией о ваших потребностях в документации и о том, какие функции зрелой системы документации вам нужны?

Я думаю, что говорить «использовать Markdown» слишком упрощенно.

Markdown — это DSL для HTML. Это все. Вы действительно скажете: «Документы — это решенная проблема, давайте использовать HTML!»

Нам нужна настоящая система документации, такая как Sphinx.

• Markdown не может генерировать ToC.
• Markdown не может связываться между темами (вам нужно делать ссылки вручную)
• Markdown не может делать такие вещи, как многоязычная поддержка или поддержка нескольких версий.

Я поддерживаю Read The Docs от @ericholscher , а точнее Sphinx и reStructuredText.

Или используйте DOxygen, и vNext никогда не будет выпущен ;)

Как насчет чего-то похожего на Roslyn или AngularJS? http://source.roslyn.codeplex.com/ https://docs.angularjs.org/api

Markdown очень хорошо работает для большинства других проектов на GitHub. +1 за уценку.

@shanselman , относительные ссылки?

Я думаю, что использование Sphinx будет работать.
@issafram Примеры здесь:
http://sphinx-doc.org/
https://docs.python.org/3/tutorial/index.html

@akoeplinger Мы хотели бы что-то, из чего мы могли бы легко создать оглавление и легко связать страницы. Мы также хотели бы что-то, что может генерировать различные форматы документов, включая HTML, PDF и ePub. Документы также должны быть доступны для чтения на мобильных устройствах.

@issafram Markdown отлично подходит, когда ваши документы состоят из сотни страниц, а скорее всего меньше. Но тысячи страниц и взаимосвязанные оглавления? Поддерживать приложения в актуальном состоянии? Связывание документов ASP.NET и .NET? Это будет беспорядок.

Имейте в виду, если вы хотите, чтобы это был действительно открытый исходный код и, следовательно, что-то поощряющее вклад, система должна быть максимально простой, без кривой обучения. Markdown не может генерировать ToC сам по себе, но относительно простой код может генерировать ToC из Markdown.
Мы в Orchard очень довольны нашей системой, которая представляет собой Markdown на Github, а также сайт Azure с очень небольшим кодом (для индексации и поиска Lucene, а также создания ToC), который автоматически обновляется каждый раз, когда репозиторий загружается. Сверхпростые, знакомые инструменты.
Единственное, что мне в нем не нравится, так это отсутствие метаданных (мы извлекаем заголовки из имен файлов), но и для этого есть решения, такие как заголовки Jeckyll YAML (поддерживается Github) или мой собственный формат Snippable.

@issafram Это плохо работает, например, с огромными кодовыми базами с МНОЖЕСТВОМ документов и рефакторингом. Переименуйте класс и _bye bye_ относительные ссылки.

_edit_: Я опоздал на игру :P

Рад слышать, что документация по ASP.NET будет на тысячи страниц ;) Тем не менее, KISS.

@bleroy Взгляните на это http://read-the-docs.readthedocs.org/en/latest/ и на rST, который его сделал. https://github.com/rtfd/readthedocs.org/blob/master/docs/index.rst

Конечно, это здорово. Просто делимся своим опытом. Я понимаю, что вы находитесь в другом масштабе.

rST - лучший вариант здесь, руки. Поскольку это ASP.NET, наличие чего-то достаточно умного для обновления его индексов (с точки зрения ToC или даже с точки зрения списка классов), вероятно, является главным приоритетом.

В идеале я бы запустил что-то в рабочем процессе сборки, чтобы получить все эти файлы .XML, сгенерированные из двоичных файлов, а затем пропустить их через процессор для создания файлов, которые затем публикуются на сервере. Точный инструмент... Я понятия не имею. Многие упоминались. Я бы порекомендовал создать свой собственный и открыть исходный код. Да, да... Дебаты о создании и покупке, но я ненавижу использовать инструменты с неуправляемыми ресурсами, такие как некоторые из вышеперечисленных. В любом случае, это звучит идеально... Вероятно, у вас есть ограничения по бюджету и времени, а что нет.

@issafram Если вы все в конечном итоге будете использовать Sphinx/RTD, что-то вроде Breathe может оказаться рабочим подходом: http://breathe.readthedocs.org/en/latest/ — это интеграция со Sphinx и Doxygen, которая использует XML-файлы Doxygen.

@issafram Мне кажется, вы описываете SHFB ... (На самом деле Sandcastle , SHFB просто делает его более приятным в использовании: P)

Да, вам нужен препроцессор/постпроцессор, вы можете связать относительность внутри документа с GHMD для TOC. Для наших проектов мы создали собственный, в основном используя .Net doc XML и основанный на соглашениях, объединенный с образцом кода и другим статическим содержимым, написанным в MD. Конечным результатом является HTML.

Наличие кода и редакционного статического контента в MD облегчило бы создание PR. Что мне нравится в уценке как исходном формате, так это то, что она намного чище, чем HTML, XML и т. д. Делает аудит простым и хорошо подходит для контроля версий.

Нам нужен чистый и простой инструмент документирования на основе соглашений для .Net, я не нашел его, если есть, я хотел бы получить информацию. И с удовольствием внесу в это свой вклад.

Что касается ремонтопригодности и связи между проектами. Intersphinx — мощный способ сделать это семантическим способом. Это позволяет вам каталогизировать все ссылки (будь то код или проза) и ссылаться на них явно в разных проектах.

Документы здесь: http://sphinx-doc.org/latest/ext/intersphinx.html

Это та функциональность, которой нет у чего-то вроде Markdown, насколько мне известно.

Согласен, что уценка — не лучшее решение, но пока нам нужно простое решение. Давай, мы разработчики, поэтому мы можем расширить это, если это необходимо. Github поддерживает уценку, VSO недавно поддерживает уценку из представления кода. Нужны ли нам дебаты. Извините, если я слишком прямолинеен.

Уценка +1

@ctsni Я признаю, что Markdown _felt_ кажется лучшим выбором на первый взгляд / мысль. Но чем больше я думаю об этом, тем больше мне кажется, что мы пытаемся забить квадратный колышек в круглое отверстие.

По общему признанию, у меня нет хорошей альтернативы, поэтому я приношу свои извинения за то, что на самом деле мало помог, но даже при расширении Markdown я не _чувствую_, что в итоге мы получим что-то такое же красивое, чистое и аккуратное Markdown, какое мы имеем сейчас _с учетом требования_.

Похоже, вы хотите воспроизвести существующую документацию MSDN в формате с открытым исходным кодом? Это справедливо? Вам нужно решение для работы с обзорными описаниями, учебными пособиями, примерами кода и документацией по API? Или это подмножество этого?

Я не уверен, что есть одно решение, скорее набор инструментов, результаты которых можно комбинировать. Я вижу, что делает ReadTheDocs — собирает несколько источников в один связный набор документации. Таким образом, Markdown является правильным ответом на часть решения (например, описания и учебные пособия), но не является ли полной картиной?

Открытый вопрос: можно ли извлечь приложения и оглавление непосредственно из уценки? Мне не кажется слишком сложным? Я предвзят. Я не работал над системой с тысячами страниц... Извините, @shanselman , я действительно не могу поделиться мудростью, кроме того, что знаю.

@craignicol Все, что меньше текущей документации MSDN, было бы для меня огромным разочарованием. Я всегда всем говорю, что лучшая документация (по структуре, формулировкам и всему прочему) находится в MSDN. Я видел много документации, но большинство, если не все, даже близко не соответствуют «качеству MSDN» (конечно, ИМХО). Сказав это: большой фактор, конечно, заключается в том, что люди, стоящие за документацией MSDN, так хорошо заботятся о фактическом _content_ MSDN; структура, макет, дизайн и все, что у вас есть, на втором месте.

Возможно, тангенциальное, но было бы очень неплохо иметь что-то вроде тире . Веб-разработка развивается так быстро, а новые технологии влияют друг на друга, что я ловлю себя на поиске фрагментов информации тут и там. Возможность получить доступ ко всему в одном месте, которое можно вызвать с помощью нескольких нажатий клавиш, невероятно полезна. Подобные попытки есть на http://zealdocs.org/ для Linux и Windows.

@craignicol Согласен, цель состоит в том, чтобы иметь документы качества MSDN с открытым исходным кодом, которые легче поддерживать и обновлять.

@ciriarte Существует поддержка перевода документов Sphinx в Dash: https://pypi.python.org/pypi/doc2dash — мы рассмотрели автоматическое создание набора Dash на RTD.org, но в настоящее время оно не развернуто.

Я думаю, что @shanselman лучше всего выразился выше: Markdown - это не ответ в большей степени, чем HTML, Word или .txt. Markdown — это в первую очередь описание презентации — необходимо что-то для создания Markdown (или HTML, документа Word, файла .txt и т. д.)

Я думаю, мой вопрос будет в том, откуда вы видите этот контент? Это будет написано от руки? Автоматически генерируется из кода? Встроены в комментарии?

Я согласен с @craignicol набором инструментов для слияния автоматически сгенерированного контента со «статическими» страницами GH Markdown для искусственных образцов и редакционного контента, которые не работают в сборке XML. Результатом может быть статический html на GHPages, PDF или что-то еще.
Препроцессор может обнаруживать любой потерянный статический контент, если код переименован/рефакторинг Т.е.
Языковая поддержка в основном может быть дополнительными папками с той же структурой, что и нейтральная. Непереведенные документы могут затем вернуться к нейтральному или пройти через перевод Bing.

Оглядываясь назад на первоначальное предложение, можно согласиться с @danroth27 по уценке для формата и readthedocs для сборки. Спасибо.

Гибкость readthedocs.org + Sphinx может обеспечить эквивалентность с MSDN, если она недоступна.

@ciriarte Вероятно, это также можно было бы поддерживать с помощью экспортируемых архивов для программы чтения MSDN.

@jalcine @ericholscher звучит фантастически.

@RobThree Я надеюсь, что команду, которая в настоящее время ведет документацию, можно будет убедить перейти на новый формат, иначе это упражнение не стоит делать.

@ctsni это возможно - я написал анализатор ToC уценки на python, который берет список файлов и генерирует ToC. Сложная часть заключается в аннотировании исходных файлов, чтобы синтаксический анализатор знал, что извлекать для создания ToC и приложений. Промежуточный формат, будь то Markdown или rST, не имеет значения, главное правильно получить метаданные.

Глядя на документы MSDN, две ключевые части метаданных, которые наиболее важны для гиперссылок, — это крючки API, позволяющие проходить код, и концептуальные крючки (например, безопасность), которые создают тему, охватывающую API, учебные пособия, и информация об архитектуре. Если часть API сделана правильно, я уверен, что остальная часть контента может быть адаптирована в соответствии с требованиями. Мне нравится идея Dash, но я думаю, что ReadTheDocs и Sphinx ближе всего к тому, что мне нравится в MSDN, но я думаю, что их нужно будет адаптировать для обработки богатой структуры тем и руководств, которые есть в MSDN.

Меня интересует вся эта концепция. Я имею в виду, что мне нравится идея открыть цепочку документации с открытым исходным кодом и привлечь сообщество, но делать это вне MSDN отчасти дает мне волю. Из того, что кажется (и могло быть) началом .NET, мы обратились к MSDN за канонической ссылкой на любой Microsoft API. От WinForms до WebForms — все в одном месте, с хорошими перекрестными ссылками и единообразным форматированием. Я не могу не задаться вопросом, принесет ли то, что получено от этого усилия, достаточно преимуществ, чтобы перевесить фрагментацию и потерю согласованности. Не говоря уже о том, что оно того не стоит, и, по-видимому, эти обсуждения уже состоялись, но информация к размышлению.

+1 для Сфинкса

Я очень люблю формат и инструменты readthedocs, и они очень хорошо работают для многих проектов. Не изобретайте велосипед. Уценка в порядке. Я думаю, что если вы не можете описать это с помощью уценки, значит, вы пытаетесь сделать что-то слишком сложное. Я, например, был бы рад внести свой вклад, если бы формат и уровень трения были низкими. Вики MSDN вроде как достигла этого, но большая часть ее была закрыта, и она превратилась в бесплодную пустыню со старым контентом. Сообщество PHP, кажется, довольно хорошо справляется со своей системой документации (хотя их комментарии иногда проваливаются в кроличьи норы). Я думаю, что упрощение с помощью уценки будет работать, но, вероятно, должен быть какой-то инструмент индексации/генерации для «основного документа» или что-то еще, чтобы собрать его вместе и синхронизировать. Почти как система сборки зависимостей для тысяч фрагментов/документов уценки.

Я думаю, Markdown для текстовых фрагментов. Передняя часть Yaml или файлы json для метаданных. Пользовательский процессор на основе .NET с расширяемой моделью плагинов, чтобы легко добавлять синтаксис для необычных вещей, таких как оглавление, таблицы и т. д. Или просто используйте сначала, достаточно похожий на Markdown.

Просто сделайте MSDN с открытым исходным кодом. Если это не беспорядок :)

@somedave не знаю, как вам, но мне все труднее и труднее находить контент в MSDN, особенно высокоуровневую архитектурную документацию по неактуальным платформам. Наличие документации, связанной с кодом, и всего доступного открытого исходного кода и контроля версий — это огромное улучшение.

Действительно ли нам нужен еще один MDSN от новой Microsoft? Большая часть сгенерированной документации — пустая трата времени. Что ему нужно, так это описание и примеры, но так часто этого не хватает, оставляя только базовую информацию, которая у меня уже есть из системы типов. Имея легкий доступ к источнику, мы теперь можем узнать, что что-то действительно делает в любом случае. Статьи, объяснения и тестовые примеры использования намного лучше, особенно если они созданы в ответ на спрос, например, вопросы о переполнении стека.

@ danroth27 danroth27 , вы говорите исключительно о документации javadoc/xmldoc или о документации в целом? То есть этот 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?

Дгени https://github.com/angular/dgeni

Определенно HTML, но с возможностью его локального использования — скажем, для установки на локальный IIS (или просто локально).

Пожалуйста, создайте конвейер Sandcastle и SHFB и помогите сделать его лучше (более простым и «дружественным к открытому исходному коду»). Можно добавить поддержку авторинга уценки (для концептуального контента) и рендеринга (некоторые старты в этом направлении уже сделаны).
Поддержка популярных (полмиллиона загрузок для SHFB) инструментов на основе .NET имеет большое значение для экспериментальной проверки. Идиомы просачиваются из инструментов в сам проект. Например, в .NET очень важно поддерживать многоязычные фрагменты кода, чтобы VB.NET и F# можно было поддерживать на платформе как жизнеспособные языки. Sandcastle и вывод в стиле MSDN прекрасно справляются с этой задачей.

Проблема с reStructuredText в том, что он похож на Markdown, но не совсем. Таким образом, это становится еще одним форматом для обучения. В настоящее время SHFB выполняет свою работу, но это не очень приятный опыт. Что-то лучше, чем ничего, и я бесконечно благодарю EWoodruff за то, что он так долго поддерживает и обновляет это.

С точки зрения разработчика .NET действительно хороший инструмент для создания документов с открытым исходным кодом для .NET по-прежнему необходим/желателен. На мой взгляд, это предпочтительный инструмент, который позволяет писать длинные тексты с помощью Markdown, потому что это то, что известно и приятно использовать.

Я знаю, что команды MS, вероятно, хотят что-то запустить и запустить asp.net 5, но это затрагивает давнюю боль, которую испытывают разработчики.

Одно из моих предложений — работать с http://commonmark.org/ над разработкой модулей commonmark и рассмотреть возможность улучшения чего-то вроде https://github.com/Knagis/CommonMark.NET.

В противном случае, по крайней мере, будьте готовы заменить систему документов после первого выпуска, чтобы сообщество не застряло на чем-то, что вызывает много трений в использовании... снова.

Также еще одна болевая точка. Документы должны быть доступны в каком-либо формате, который можно использовать локально. Есть люди, которые работают в системах, не подключенных к Интернету, и автономная документация может спасти им жизнь. Мне приходилось работать в таких условиях, и автономная документация бесценна.

@ryanbnl Мы ищем решение как для справочной документации API, так и для концептуального контента.

@michaelherndon Я полностью согласен с тем, что для .NET нужен хороший инструмент для создания документов с открытым исходным кодом! Вы также правы в том, что нам нужно быстро запустить что-то для ASP.NET. Если бы появилось сообщество, поддерживающее документацию на основе .NET, мы, конечно, были бы открыты для ее принятия. Мы также согласны с тем, что доступ к документации в автономном режиме является обязательным требованием.

Ладно, это понятно :) Документы по API стоит поискать на doxygen. Он действительно мощный и может генерировать диаграммы классов (которые могут быть неоценимы в определенных ситуациях). Я провел подробное сравнение doxygen/sandcastle в прошлом году, могу выслать вам копию, если это поможет? Он содержит множество примеров + пошаговое руководство по установке (doxygen сложно установить) ;)

Похоже, одна из проблем заключается в том, чтобы сохранить документацию с открытым исходным кодом, чтобы другие могли внести свой вклад. Во-вторых, это инструмент, используемый для создания и ведения такой документации.
Разве у нас нет инструмента с открытым исходным кодом, который позволяет создавать html/GHMD для окончательной загрузки. Любой, кому необходимо внести свой вклад, может использовать этот инструмент и изменять страницы в зависимости от их уровня доступа на github. Инструмент должен быть гибким, чтобы его можно было использовать как для небольших, так и для крупных проектов. Этот инструмент может быть расширением VS, которое создает документацию для любого проекта, а образец документации для базовых шаблонов может быть необязательным, как текущие параметры аутентификации в новых проектах.

@farrukhsubhani инструмент, вероятно, не должен зависеть от VS: если мы хотим, чтобы пользователи Mac и Linux использовали и вносили свой вклад в ASP.NET, инструментарий должен быть кроссплатформенным и не должен требовать огромной установки.

Я заметил, что сейчас в источниках очень мало комментариев к документации. хотя это варьируется от файла к файлу. Было ли принято решение об использовании этого в качестве исходных данных для справочной документации, или это зависело от отдельных разработчиков?

Что бы это обсуждение ни дало, я хотел бы высказаться за то, чтобы, по крайней мере, иметь это в будущем, с поддержкой компилятора для создания этих XML-файлов (или другого формата, который подключается к IntelliSense) и сегодняшним опытом редактирования и выделения, который особенно хорош с Рослин в Visual Studio.

Может быть, другие резко не согласны, но мне особенно не нравится редактировать /* */ стиль комментариев для этого и ряд выровненных *. Пожалуйста, скажи мне, что мне не нужно беспокоиться ;)

@danroth27

Просто некоторые мысли и спасибо заранее, по крайней мере, читать и думать об этом.

Реструктурированный текст похож на PITA для добавления простых вещей, таких как ссылка или заголовок. Я бы взял комментарии кода Javadoc или просто ванильный html в любой день недели.

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

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

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

check out the _aspnet homepage.

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

Я хотел бы попросить, чтобы aspnet внутренне обсудил работу с сообществом по установлению некоторых целей / спецификаций в инструменте документации .net и, возможно, предоставил некоторые творческие стимулы, такие как признание или что-то в этом роде. Я также прошу всех вас обсудить настройку проекта через .NET Foundation. Это также может послужить достойным стажером / летним проектом, подобным коду, для работы студентов cs, поскольку это, скорее всего, потребует создания синтаксического анализатора.

Это не направлено на вас или кого-либо в частности, но в циклах разработки уже поздно начинать публиковать и думать об этом, поскольку это заставляет вас, ребята, зайти в угол, чтобы использовать что-то, что работает, но не то, что поражает. все сценарии, включая низкий барьер для входа.

Гипотетически говоря, общение с сообществом ранее могло, по крайней мере, создать инструмент, который можно было бы использовать, и его можно было бы создать параллельно на основе всей тяжелой работы команды aspnet в качестве хорошего примера aspnet 5.

При этом, если бы это было запущено сейчас, оно могло бы быть готово, скажем, для использования .NET core 5.

@ericwj все общедоступные API-интерфейсы должны иметь ¹ комментарии к документам XML. Однако в начале проекта мы смягчили это требование, потому что написание большого количества документации по API, которые, как мы знали, значительно изменятся, считалось в значительной степени напрасной тратой усилий. Однако во всех коммитах за последние несколько месяцев должно присутствовать значительное количество документации. Действительно, есть еще много дыр, но команда обязана предоставить эту документацию. При исправлении документации мы, как правило, сосредотачиваемся на более важных API, к которым, по нашему мнению, получат доступ разработчики, и переводим более эзотерические API в менее документированный статус (который мы все еще надеемся когда-нибудь заполнить).

¹ требуется _прилагательное_

Что-то необязательное.
Также может означать что-то, что _является_ необязательным в контексте комментариев XML-документа.

@michaelherndon Кстати, этот проект уже является частью .NET Foundation .

@Eilon , в контексте говорилось о добавлении инструмента документации .net, а не aspnet 5.

@michaelherndon а, понял, спасибо!

@shanselman @danroth27 , в прошлую пятницу я проинформировал своего менеджера, и он связался с менеджерами основной группы MSDN по поводу этой темы. Они должны связаться с вами по поводу вашей документации. Хорошего дня.

@michaelherndon Я согласен, что синтаксис заголовка немного более подробный. Другим общим случаем является ссылка на функцию или страницу в документации, где сияет RST:

More Info
=========

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

Делаем что-то подобное в 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).

Я не вижу здесь большой принципиальной разницы. RST со Sphinx дает вам большой набор ценных справочных функций, которые будут потеряны или связаны несемантически с URL-адресом или HTML-документом в случае Markdown.

Еще одним интересным лакомым кусочком в этом направлении является этот документ о том, как писать RST и MD совместимым образом: https://gist.github.com/dupuy/1855764. Markdown обычно поддерживает заголовки в стиле RST, так что этот стиль заголовков будет работать в обоих случаях.

Вы также можете настроить Sphinx или другой инструментарий для понимания базового синтаксиса Markdown с расширением , если оно мешает показу.

Я помню, как говорил на панели OSS на MVP Submit около 18 месяцев назад, что в .NET нет хороших вариантов документации :stuck_out_tongue_closed_eyes:

Что мне действительно хотелось бы увидеть, так это способ генерировать уценку или сначала плюс оглавление из документации .NET XML. Затем его можно загрузить во что-то вроде readthedocs или github wiki.

В Sandcastle уже есть тонна кода для чтения XML-документации .NET, и он расширяется за счет новых стилей и типов вывода. Вы могли бы опираться на это.

Как посмотреть на эту ветку и понять, какой был вывод, принято ли решение, и если да, то какое?

https://github.com/aspnet/Документы

Почему вы, ребята, не используете DocFX?

Когда мы начали писать документацию для ASP.NET 5, проект docfx все еще находился на ранних стадиях разработки. Sphinx по-прежнему является гораздо более зрелой и многофункциональной структурой документации. Кроме того, Read the Docs предлагает действительно хорошее решение для размещения документации.

Тем не менее, мы поддерживаем проект docfx как решение для документирования .NET, и приятно видеть, что docfx теперь имеет открытый исходный код! Мы уже планируем использовать docfx для справочной документации по API и планируем перейти на docfx по мере его развития.

Просто кажется позорным идти в двух разных направлениях за ворота, когда кажется, что docfx - это то, что использует MSDN, по крайней мере, исходя из встроенных тем.

@simonmurdock docfx (пока) не поддерживает создание автономных документов, таких как PDF

Да , @cocowalla , я в вечном движении по поводу состояния профсоюза с документацией. Сейчас я пишу свои статьи в sphinx, но нет хорошего способа генерировать документы API, интегрированные в sphinx.

Текущий план — Sphinx для всех статей и отдельный сайт для выходных данных DocFX, пока Sphinx ApiDocs не станет немного лучше.

@simonmurdock Вот что мы сейчас делаем для создания справочных документов API для ASP.NET, используя комбинацию docfx и расширения autoapi Sphinx: https://github.com/aspnet/apidocs. Это все еще немного грубо, но мы работаем с людьми из Read the Docs над кучей улучшений.

@danroth27 Так много голосов было за RsT, однако в итоге вы выбрали MD? Когда я нажимаю EDIT на любой странице https://docs.microsoft.com/en-us/aspnet/core/ , я вижу исходный файл MD на GitHub.
Так почему МД?

Некоторое время мы использовали RST и http://readthedocs.com для документов ASP.NET Core и EF Core, но недавно Microsoft создала собственную инфраструктуру документации на http://docs.microsoft.com , поэтому мы перешли на согласовываться с этим. Хотя уценка не является таким зрелым языком документации, как reStructuredText, она более знакома широкой аудитории. По этой причине даже Read the Docs поддерживает оба формата.

@ danroth27 Означает ли это, что Microsoft создала собственный генератор/движок документации с закрытым исходным кодом, который использует уценку? Что остается за https://docs.microsoft.com?

Означает ли это, что Microsoft создала собственный генератор/движок документации с закрытым исходным кодом, который использует уценку?

Нет. Механизм документирования https://docs.microsoft.com — это DocFX , он построен на .NET и имеет полностью открытый исходный код. Он использует уценку для своего формата.

Привет

Я могу немного опоздать с публикацией этого.

Мне просто интересно, есть ли API, фреймворк или инструменты, которые позволяют нам создать сайт документации, подобный тому, что для https://docs.microsoft.com? Мне лично нравится, как представлена ​​документация Microsoft, @danroth27 упомянул DocFX, который является используемым движком, я просто хочу знать, является ли сам сайт чем-то, что сделано с нуля, или есть шаблон или пакет, который мы можем использовать для создания такого же внешнего вида? не совсем то же самое, но что-то, что мы можем изменить :)

Спасибо!
Джуд Алькиса.

Чем больше я читаю о DocFx , тем больше он мне нравится — скоро попробую.

Как мы можем создать собственный веб-сайт с документацией, такой как https://docs.microsoft.com/ , не изобретая заново велосипед? Мы используем размещенный readthedocs для документов по python и размещенный doxygen для документов по c/c++.

Как лучше всего собрать всю документацию по API под одной крышей? Судя по этой ветке, многие люди используют sphinx/readthedocs, но как вы конвертируете документацию .XML в правильный формат для этих инструментов?