Aspnetcore: ASP.NET 5 문서에는 어떤 형식을 사용해야 합니까?

http://shfb.codeplex.com

아니면 그냥 새로운 것을 만드십시오.

GH Markdown을 생성하는 좋은 전처리기는 훌륭할 것입니다.

Markdown(또는 GitHub Flavored Markdown)에 대해 +1입니다. 일부 기능이 부족할 수 있지만 꽤 잘 알려져 있고 배우고 사용하기가 매우 쉽습니다. 몇 가지 옵션을 언급했듯이 호스팅 위치에 대한 최종 결정에 따라 달라질 수 있습니다.

안녕 다니엘,
당신의 기여에 감사드립니다.
주니어 개발자로서 http://rustbyexample.com/ 과 유사한 사이드바의 제목으로 문서를 구성하는 것이 쉽다는 것을 알았습니다.
(임호)

-1 새로운 것을 만드는 일.
기존에 작업하고 가능한 경우 개선하려면 +1합니다.

@danroth27 문서화 요구 사항과 성숙한 문서화 시스템의 어떤 기능이 필요한지에 대한 세부 정보를 공유할 수 있습니까?

"마크다운을 사용하라"는 말은 너무 단순하다고 생각합니다.

마크다운은 HTML용 DSL입니다. 그게 다야. "문서는 해결된 문제입니다. HTML을 사용합시다!"라고 말할 수 있습니까?

Sphinx와 같은 실제 문서 시스템이 필요합니다.

• 마크다운은 목차를 생성할 수 없습니다.
• Markdown은 주제 사이를 연결할 수 없습니다(링크를 수동으로 수행해야 함).
• Markdown은 다국어 지원 또는 다중 버전 지원과 같은 작업을 수행할 수 없습니다.

저는 @ericholscher 의 Read The Docs를 지지하지만, 보다 구체적으로 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은 문서가 100페이지일 때 훌륭합니다. 그러나 수천 페이지와 연동 목차? 부록을 최신 상태로 유지하시겠습니까? ASP.NET과 .NET 문서를 연결하시겠습니까? 엉망이 될거야.

이것이 정말로 오픈 소스가 되고 기여를 장려하는 것을 원한다면 시스템은 학습 곡선 없이 가능한 한 단순해야 합니다. Markdown은 자체적으로 ToC를 생성할 수 없지만 비교적 간단한 코드는 Markdown에서 ToC를 생성할 수 있습니다.
Orchard의 우리 시스템은 Github의 Markdown과 Repo가 푸시될 때마다 자동 업데이트되는 매우 적은 코드(Lucene 인덱싱 및 검색 및 ToC 생성용)가 있는 Azure 사이트인 시스템에 매우 만족합니다. 매우 간단하고 친숙한 도구.
내가 유일하게 마음에 들지 않는 점은 메타데이터가 없다는 것(파일 이름에서 제목을 추출함)이지만 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과의 통합으로 Doxygen XML 파일.

@issafram 당신이 SHFB 에 대해 설명하고 있다고 생각합니다 ... (실제로 Sandcastle , SHFB는 사용하기가 더 즐겁습니다 :P)

예, 전처리기/후처리기가 필요합니다. TOC용 GHMD를 사용하여 문서 내의 상대성을 연결할 수 있습니다. 우리 프로젝트를 위해 우리는 기본적으로 .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은 언뜻 보기에 가장 좋은 선택이라고 _느꼈습니다_. 하지만 생각하면 할수록 네모난 못을 동그란 구멍에 망치로 박는 것 같은 기분이 듭니다.

물론 좋은 대안이 없기 때문에 실제로 많은 기여를 하지 못한 점에 대해 사과드립니다. 그러나 Markdown을 확장할 때에도 우리가 지금과 같이 예쁘고 깨끗하고 깔끔한 Markdown을 갖게 될 것이라고는 생각하지 않습니다. 요구 사항_.

기존 MSDN 문서를 오픈 소스 형식으로 복제하려는 것 같습니까? 공정한가요? 개요 설명, 자습서, 코드 샘플 및 API 문서를 처리할 솔루션이 필요하십니까? 아니면 그 부분집합인가요?

나는 하나의 솔루션이 있다고 확신하지 못합니다. 출력을 결합할 수 있는 도구 모음이 더 많습니다. ReadTheDocs가 하는 일을 볼 수 있습니다. 여러 소스를 일관된 문서 세트로 끌어오는 것입니다. 따라서 Markdown은 솔루션의 일부(예: 설명 및 자습서)에 대한 유효한 답변이지만 전체 그림이 아닌가요?

열린 질문: 마크다운에서 부록과 목차를 직접 추출할 수 있습니까? 내가 보기엔 너무 어려운 것 같지 않아? 나는 편향적이다. 저는 수천 페이지가 있는 시스템에서 작업한 적이 없습니다... 죄송합니다 @shanselman , 제가 ​​아는 것 이상으로 지혜를 기여할 수는 없습니다.

@craignicol 현재 MSDN 문서보다 낮은 것은 나에게 큰 실망이 될 것입니다. 저는 항상 모든 사람에게 최고의 문서(구조, 문구 및 이에 관한 모든 것)가 MSDN에 있다고 말합니다. 나는 많은 문서를 보았지만 전부는 아니더라도 대부분은 "MSDN 품질"(IMHO는 물론)에 가깝지 않습니다. 즉, 큰 요인은 물론 MSDN 문서 뒤에 있는 사람들이 MSDN의 실제 _content_를 잘 관리한다는 것입니다. 구조, 레이아웃, 디자인 및 소유물이 두 번째로 중요합니다.

아마도 접선일 수 있지만 dash 와 같은 것이 있으면 매우 좋을 것입니다. 웹 개발은 매우 빠르게 발전하고 새로운 기술은 서로 영향을 미치기 때문에 여기저기서 정보를 검색하고 있습니다. 일부 키 입력을 통해 호출할 수 있는 포함된 단일 위치에서 모든 것에 액세스할 수 있다는 것은 매우 유용합니다. Linux 및 Windows용 http://zealdocs.org/ 비슷한 노력이 있습니다.

@craignicol 동의합니다. 목표는 오픈 소스이고 유지 관리 및 최신 상태를 유지하기 쉬운 MSDN 품질 문서를 ​​보유하는 것입니다.

@ciriarte Sphinx 문서를 Dash로 변환하는 지원이 있습니다. https://pypi.python.org/pypi/doc2dash -- RTD.org에서 자동 Dash 세트 생성을 살펴보았지만 현재 배포하지 않았습니다.

나는 @shanselman 이 그것을 가장 잘 표현했다고 생각합니다. HTML, Word 또는 .txt가 답이 될 것보다 Markdown이 답이 아닙니다. Markdown은 주로 프레젠테이션 설명입니다. 필요한 것은 Markdown(또는 HTML, Word 문서, .txt 파일 등)을 생성하는 것입니다.

제 질문은 그 콘텐츠가 어디에서 오는지 보십니까? 손글씨로 쓸까요? 코드에서 자동 생성? 댓글에 포함?

자동 생성 콘텐츠를 어셈블리 XML에서 사용할 수 없는 사람이 만든 샘플 및 편집 콘텐츠에 대한 "정적" GH 마크다운 페이지와 병합하기 위한 도구 모음 @craignicol 에 동의합니다. 출력 결과는 GHPages, PDF 등의 정적 html이 될 수 있습니다.
코드 이름이 변경/리팩터링된 경우 전처리기가 분리된 정적 콘텐츠를 감지할 수 있음
언어 지원은 기본적으로 중립과 동일한 구조의 선택적 폴더일 수 있습니다. 번역되지 않은 문서는 중립으로 대체되거나 Bing 번역을 통해 이동할 수 있습니다.

원래 제안을 되돌아보면 형식에 대한 마크다운 및 빌드에 대한 readthedocs에 대한 @danroth27 에 동의할 것입니다. 감사 해요.

readthedocs.org + Sphinx의 유연성은 접근할 수 없는 경우 MSDN과 동등함을 허용할 수 있습니다.

@ciriarte MSDN 리더용 내보내기 가능한 아카이브에서도 지원될 수 있습니다.

@jalcine @ericholscher는 환상적으로 들립니다.

@RobThree 현재 문서를 유지 관리하는 팀이 새 형식으로 이동하도록 설득할 수 있기를 바랍니다. 그렇지 않으면 이 연습을 수행할 가치가 없습니다.

@ctsni 가능합니다 - 파이썬으로 마크다운 ToC 파서를 작성했습니다. 이 파서는 파일 목록을 가져와서 ToC를 생성합니다. 까다로운 부분은 파서가 ToC 및 부록을 생성하기 위해 추출할 내용을 알 수 있도록 소스 파일에 주석을 추가하는 것입니다. Markdown이든 rST이든 중간 형식은 중요하지 않으며 메타데이터를 올바르게 얻는 것이 핵심입니다.

MSDN 문서를 보면 하이퍼링크에 가장 중요한 두 가지 메타데이터는 코드 순회를 허용하는 API 후크와 API, 자습서, 및 아키텍처 정보. API 부분만 제대로 된다면 나머지 내용도 그에 맞게 수정될 수 있을 거라 확신합니다. 나는 Dash의 아이디어를 좋아하지만 ReadTheDocs와 Sphinx는 내가 MSDN에 대해 좋아하는 것에 가장 가깝다고 생각하지만 MSDN이 가지고 있는 풍부한 주제와 튜토리얼 구조를 처리하기 위해 적응해야 한다고 생각합니다.

이 전체 개념이 궁금합니다. 내 말은, 나는 문서 체인을 오픈 소싱하고 커뮤니티를 참여시키는 아이디어를 좋아하지만 MSDN 외부에서 그것을 하는 것은 나에게 의지를 줍니다. .NET의 시작처럼 보이는(그리고 그랬을 수도 있는) 것에서 우리는 모든 Microsoft API에 대한 표준 참조를 위해 MSDN으로 이동했습니다. WinForms에서 WebForms에 이르기까지 모든 것이 한 곳에서 훌륭하게 상호 참조되고 일관되게 형식화됩니다. 이러한 노력을 통해 얻은 것이 단편화와 일관성 상실을 능가할 만큼 충분한 이점을 제공할 수 있을지 궁금하지 않을 수 없습니다. 그만한 가치가 없다고 말하는 것이 아니라 아마도 이러한 논의는 이미 진행되었지만 생각할 거리가 될 것입니다.

스핑크스의 경우 +1

나는 정말로 readthedocs 형식과 도구를 파고 있으며 많은 프로젝트에서 잘 작동합니다. 바퀴를 재발명하지 마십시오. 마크다운 괜찮습니다. 마크다운으로 설명할 수 없다면 너무 복잡한 작업을 하려는 것입니다. 형식과 마찰 수준이 낮으면 기꺼이 기여하겠습니다. MSDN wiki는 일종의 접근 방식이었지만 대부분이 폐쇄되어 오래된 콘텐츠의 황무지가 되었습니다. PHP 커뮤니티는 문서 시스템에서 상당히 잘 수행하고 있는 것 같습니다(비록 그들의 주석은 때때로 토끼 구멍으로 떨어지긴 하지만). 마크다운을 사용하여 단순하게 유지하는 것이 효과가 있다고 생각하지만 "마스터 문서"에 대한 일종의 인덱싱/생성 도구나 문서를 함께 가져와 동기화 상태로 유지하는 데 필요한 것이 있을 것입니다. 수천 개의 마크다운 스니펫/문서에 대한 종속성 빌드 시스템과 거의 비슷합니다.

나는 텍스트 조각에 대한 Markdown을 생각합니다. 메타 데이터용 Yaml 전면 또는 json 파일. TOC 및 테이블 등과 같은 멋진 항목에 대한 구문을 쉽게 추가할 수 있는 확장 가능한 플러그인 모델이 있는 사용자 지정 .NET 기반 프로세서. 또는 Markdown과 충분히 유사한 rst를 사용하십시오.

MSDN을 오픈 소스로 만드십시오. 엉망이 아니라면 :)

@somedave 는 당신에 대해 모르지만 MSDN에서 콘텐츠, 특히 최신이 아닌 프레임워크에 대한 높은 수준의 아키텍처 문서를 찾는 것이 점점 더 어렵다는 것을 알게 되었습니다. 문서를 코드에 연결하고 사용 가능한 모든 오픈 소스와 버전 관리를 하면 엄청난 개선이 이루어집니다.

새로운 Microsoft의 또 다른 MDSN을 정말로 원합니까? 생성된 문서의 대부분은 시간 낭비입니다. 필요한 것은 내러티브와 예제이지만 유형 시스템에서 이미 가지고 있는 기본 정보만 남기고 누락되는 경우가 많습니다. 소스에 쉽게 액세스할 수 있으므로 이제 실제로 어떤 작업이 수행되는지 알 수 있습니다. 기사, 설명 및 사용 테스트 예는 특히 스택 오버플로 질문과 같은 수요에 대한 응답으로 작성된 경우 훨씬 더 좋습니다.

@ danroth27 , 순전히 javadoc/xmldoc 문서 또는 일반적인 문서에 대해 말씀하고 있습니까? 즉, http://www.asp.net/aspnet/overview/authentication-and-identity 대 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의 경우 50만 다운로드) .NET 기반 도구를 지원하는 데는 많은 dogfood 가치가 있습니다. 관용구는 도구에서 프로젝트 자체로 누출됩니다. 예를 들어 .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은 설치하기 까다롭습니다) ;)

한 가지 문제는 문서를 오픈 소스로 유지하여 다른 사람들이 기여할 수 있도록 하는 것 같습니다. 두 번째는 그러한 문서를 생성하고 유지하는 데 사용되는 도구입니다.
오픈 소스이며 최종 업로드를 위해 생성된 html/GHMD를 허용하는 도구가 없을 수 있습니까? 기여해야 하는 사람은 누구나 이 도구를 사용하고 github의 액세스 수준에 따라 페이지를 수정할 수 있습니다. 도구는 작거나 큰 프로젝트에 사용할 수 있도록 유연해야 합니다. 이 도구는 모든 프로젝트에 대한 문서를 생성하는 VS 확장일 수 있으며 기본 템플릿에 대한 샘플 문서는 새 프로젝트의 현재 인증 옵션과 같이 선택 사항일 수 있습니다.

@farrukhsubhani 도구는 VS에 의존하지 않아야 합니다. Mac 및 Linux 사용자가 ASP.NET을 사용하고 기여하도록 하려면 도구가 플랫폼 간이어야 하고 대규모 설치가 필요하지 않아야 합니다.

지금 소스에 문서 주석이 거의 없다는 것을 알았습니다. 파일마다 다르지만. 그것을 참조 문서의 입력으로 사용하는 것에 대한 결정이 있었습니까, 아니면 개별 개발자에게 달려 있습니까?

이 논의가 어떤 결과를 가져오든 간에, 저는 XML 파일(또는 IntelliSense에 연결되는 다른 형식)을 생성하기 위한 컴파일러 지원과 특히 다음과 같은 현재 편집 및 강조 표시 환경을 통해 최소한 미래에도 계속 유지하는 것에 찬성하여 말하고 싶습니다. Visual Studio의 Roslyn.

다른 사람들은 격렬하게 동의하지 않을 수도 있지만 저는 특히 /* */ 스타일 주석과 일련의 정렬된 *를 편집하는 것을 싫어합니다. 걱정할 필요가 없다고 말해주세요 ;)

@danroth27

적어도 이것에 대해 읽고 생각한 것에 대해 미리 몇 가지 생각과 감사를 드립니다.

Restructuredtext는 링크나 제목과 같은 간단한 것을 삽입하는 PITA처럼 보입니다. 나는 요일에 상관없이 Javadoc 코드 주석이나 그냥 바닐라 HTML을 사용합니다.

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

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

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

check out the _aspnet homepage.

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

저는 aspnet이 .net 문서 도구에 대한 몇 가지 목표/사양을 설정하는 데 커뮤니티와 내부적으로 논의하고 인정이나 그와 같은 무언가와 같은 창의적인 인센티브를 제공할 수 있도록 요청하고 싶습니다. 또한 .NET 기반을 통해 프로젝트를 설정하는 방법에 대해 논의해 주시기 바랍니다. 이것은 또한 파서 생성을 포함할 가능성이 높기 때문에 cs 학생들이 작업할 수 있는 프로젝트와 같은 코드의 괜찮은 인턴/여름 역할을 할 수 있습니다.

이것은 당신이나 특히 누구를 향한 것이 아니지만, 작동하지만 히트하지 않는 무언가를 사용하도록 강요하기 때문에 지금 게시하고 이에 대해 생각하기 시작하는 것은 개발 주기에서 늦었습니다. 낮은 진입 장벽을 포함한 모든 시나리오.

가설적으로 말하자면, 커뮤니티와 더 일찍 대화를 나누면 적어도 지금쯤은 사용할 수 있는 도구가 생성되었을 수 있으며, 도그푸딩 aspnet 5의 좋은 예로서 모든 aspnet 팀의 노력 위에 병렬로 구축될 수 있었습니다.

즉, 이것이 지금 시작되면 .NET Core 5를 사용할 준비가 될 수 있습니다.

@ericwj 모든 공개 API에는 XML 문서 주석이 있어야 ^합니다 . 그러나 프로젝트 초기에 크게 변경될 것으로 예상되는 API에 대한 많은 문서를 작성하는 것은 상당한 노력을 낭비하는 것으로 간주되었기 때문에 해당 요구 사항을 완화했습니다. 그러나 지난 몇 개월 동안의 모든 커밋에는 상당한 양의 문서가 있어야 합니다. 실제로 여전히 많은 구멍이 있지만 이 문서를 제공하는 것은 팀의 의무입니다. 문서를 패치할 때 우리는 개발자가 액세스할 더 중요한 API에 초점을 맞추는 경향이 있으며 더 난해한 API를 덜 문서화된 상태(언젠가 채워지기를 희망함)로 격하시키는 경향이 있습니다.

¹ 필수 _형용사_

선택 사항이 아닌 것.
XML 문서 주석의 맥락에서 _is_ 선택적이라는 것을 의미할 수도 있습니다.

@michaelherndon BTW 이 프로젝트는 이미 .NET Foundation의 일부입니다 .

@Eilon 컨텍스트는 aspnet 5가 아닌 .net 문서 도구를 추가하는 것에 대해 이야기하고 있었습니다.

@michaelherndon 아 알았습니다, 감사합니다!

@shanselman @danroth27 , 지난 금요일에 제 관리자에게 알렸고 이 관리자가 해당 스레드에 대해 MSDN Principal Group PM에게 연락했습니다. 그들은 귀하의 문서 문제에 대해 귀하에게 연락해야 합니다. 좋은 하루 되세요.

@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).

여기에는 큰 근본적인 차이가 없습니다. Sphinx가 포함된 RST는 Markdown의 경우 손실되거나 의미 없는 방식으로 URL 또는 HTML 문서에 연결될 수 있는 귀중한 참조 기능을 다양 하게 제공합니다.

이 라인에 따른 또 다른 흥미로운 정보는 RST와 MD를 호환 가능한 방식으로 작성하는 방법에 대한 이 문서입니다: https://gist.github.com/dupuy/1855764. Markdown은 일반적으로 RST 스타일 헤더를 지원하므로 헤더 스타일이 둘 다에서 작동합니다.

또한 Sphinx 또는 기타 도구를 구성하여 확장 이 포함된 기본 Markdown 구문을 이해하도록 할 수도 있습니다.

약 18개월 전 MVP Submit의 OSS 패널에서 .NET:stuck_out_tongue_closed_eyes에 문서화를 위한 좋은 옵션이 없다고 말한 것을 기억합니다.

내가 정말로 보고 싶은 것은 .NET XML 문서에서 마크다운 또는 첫 번째와 목차를 생성하는 방법입니다. 그런 다음 readthedocs 또는 github wiki와 같은 항목에 로드할 수 있습니다.

Sandcastle에는 이미 .NET XML 문서를 읽기 위한 수많은 코드가 있으며 새로운 스타일과 출력 유형으로 확장할 수 있습니다. 당신은 그것을 기반으로 할 수 있습니다.

이 스레드를 보고 결론이 무엇인지, 결정이 내려졌는지 여부, 결정이 내려졌다면 어떻게 되었는지 알아내려면 어떻게 해야 합니까?

https://github.com/aspnet/Docs

왜 DocFX를 사용하지 않습니까?

ASP.NET 5에 대한 문서 작성을 시작했을 때 docfx 프로젝트는 아직 개발 초기 단계였습니다. Sphinx 는 훨씬 더 성숙하고 기능이 풍부한 문서 프레임워크입니다. 게다가 Read Docs 는 정말 훌륭한 문서 호스팅 솔루션을 제공합니다.

즉, 우리는 .NET용 문서 솔루션으로서 docfx의 노력을 지지하며 이제 docfx 가 오픈 소스임을 알게 되어 매우 기쁩니다! 우리는 이미 API 참조 문서에 docfx를 사용할 계획이며 성숙함에 따라 docfx로 이동할 것으로 예상합니다.

docfx가 MSDN에서 사용하는 것처럼 보일 때 적어도 기본 제공 테마에 따라 두 가지 다른 방향으로 나가는 것은 부끄러운 일입니다.

@simonmurdock docfx는 (아직) PDF와 같은 오프라인 문서 생성을 지원하지 않습니다.

네 @cocowalla 저는 문서와 결합된 상태에 대해 끊임없이 변화하고 있습니다. 지금은 내 기사를 sphinx로 작성하고 있지만 sphinx 통합 API 문서를 생성하는 좋은 방법은 없습니다.

현재 계획은 Sphinx ApiDocs가 조금 더 멋지게 보일 때까지 모든 기사에 대한 Sphinx 및 DocFX의 출력에 대한 별도의 사이트입니다.

@simonmurdock 다음은 docfx와 Sphinx autoapi 확장의 조합을 사용하여 ASP.NET용 API 참조 문서를 생성하기 위해 현재 수행하는 작업입니다. https://github.com/aspnet/apidocs. 여전히 약간 거칠지만, 우리는 문서 읽기(Read Docs) 사람들과 함께 여러 가지 개선 사항에 대해 작업하고 있습니다.

@danroth27 RsT 에 너무 많은 투표가 있었지만 결국 MD를 선택 했습니까? https://docs.microsoft.com/en-us/aspnet/core/ 의 페이지에서 EDIT를 클릭하면 GitHub에 MD 소스 파일이 표시됩니다.
그렇다면 왜 MD인가?

우리는 ASP.NET Core 및 EF Core 문서에 대해 잠시 동안 RST 및 http://readthedocs.com 을 사용했지만 최근에 Microsoft는 http://docs.microsoft.com 에 자체 문서 인프라를 구축하여 다음으로 이동했습니다. 그것에 맞춰. 마크다운은 reStructuredText만큼 성숙한 문서 언어는 아니지만 더 많은 사람들에게 친숙합니다. 이러한 이유로 Read Docs는 두 형식을 모두 지원합니다.

@danroth27 마이크로소프트가 마크다운을 사용하는 자체 비오픈 소스 문서 생성기/엔진을 만들었다는 뜻인가요? https://docs.microsoft.com 뒤에 무엇이 남아 있습니까?

Microsoft가 마크다운을 사용하는 자체 비오픈 소스 문서 생성기/엔진을 만들었다는 의미입니까?

아니요. https://docs.microsoft.com 뒤에 있는 문서 엔진은 DocFX 이며 .NET을 기반으로 하며 완전히 오픈 소스입니다. 형식에 마크다운을 사용합니다.

안녕

포스팅이 조금 늦어질 수 있습니다.

https://docs.microsoft.com과 같은 문서 사이트를 만들 수 있는 API, 프레임워크 또는 도구가 있는지 궁금합니다. 저는 개인적으로 Microsoft 문서가 어떻게 제공되는지를 좋아합니다. @danroth27 은 사용된 엔진인 DocFX를 언급했습니다. 사이트 자체가 처음부터 수행된 것인지 아니면 우리가 할 수 있는 템플릿이나 패키지가 있는지 알고 싶습니다. 동일한 모양과 느낌을 생성하는 데 사용하시겠습니까? 정확히 같지는 않지만 수정할 수 있습니다. :)

감사 해요!
주드 알퀴자.

DocFx 에 대해 읽으면 읽을수록 더 마음에 듭니다. 곧 시도해 볼 것입니다.

바퀴를 다시 발명하지 않고 내부적으로 https://docs.microsoft.com/ 과 같은 자체 문서 웹 사이트를 어떻게 만들 수 있습니까? 우리는 python 문서용으로 호스팅된 readthedocs를 사용하고 c/c++ 문서용으로 호스팅된 doxygen을 사용합니다.

한 지붕 아래에서 모든 API 문서를 가져오는 가장 좋은 방법은 무엇입니까? 이 스레드를 읽으면 많은 사람들이 sphinx/readthedocs를 사용하는 것 같지만 .XML 문서를 이러한 도구에 적합한 형식으로 변환하는 방법은 무엇입니까?