Aspnetcore: Format apa yang harus kita gunakan untuk dokumentasi ASP.NET 5?

http://shfb.codeplex.com

Atau hanya membuat sesuatu yang baru.

Pra-prosesor yang baik menghasilkan GH Markdown akan sangat baik.

+1 untuk Penurunan Harga (atau Penurunan Harga GitHub). Ini mungkin kekurangan beberapa fitur tetapi cukup terkenal dan sangat mudah dipelajari dan digunakan. Saya kira itu mungkin tergantung pada keputusan akhir di mana itu akan di-host, seperti yang Anda sebutkan beberapa opsi.

Hai Daniel,
Terima kasih atas kontribusi anda.
Sebagai dev junior, saya merasa mudah untuk mengatur dokumen sebagai judul di sidebar, mirip dengan ini http://rustbyexample.com/
(MENURUT OPINI SAYA)

-1 dalam membuat sesuatu yang baru.
+1 untuk mengerjakan sesuatu yang sudah ada dan tingkatkan jika memungkinkan.

@ danroth27 Bisakah Anda membagikan lebih banyak detail tentang kebutuhan dokumentasi Anda dan fitur apa dari sistem dokumentasi matang yang Anda butuhkan?

Saya pikir mengatakan "gunakan penurunan harga" terlalu sederhana.

Penurunan harga adalah DSL untuk HTML. Itu saja. Apakah Anda benar-benar akan mengatakan "Docs adalah masalah yang terpecahkan, mari kita gunakan HTML!"

Kami membutuhkan sistem Dokumentasi yang sebenarnya seperti Sphinx.

• Penurunan harga tidak dapat menghasilkan ToC.
• Penurunan harga tidak dapat menautkan antar topik (Anda harus melakukan tautan secara manual)
• Penurunan harga tidak dapat melakukan hal-hal seperti dukungan multibahasa atau dukungan multi-versi.

Saya mendukung @ericholscher 's Read The Docs, tetapi lebih khusus Sphinx dan reStructuredText.

Atau gunakan DOxygen dan vNext tidak akan pernah dirilis ;)

Bagaimana dengan sesuatu yang mirip dengan Roslyn atau AngularJS? http://source.roslyn.codeplex.com/ https://docs.angularjs.org/api

Penurunan harga bekerja sangat baik untuk sebagian besar proyek lain di GitHub. +1 untuk Penurunan Harga.

@shanselman , tautan relatif?

Saya pikir menggunakan Sphinx akan berhasil.
@issafram Contoh di sini:
http://sphinx-doc.org/
https://docs.python.org/3/tutorial/index.html

@akoeplinger Kami ingin sesuatu yang kami dapat dengan mudah menghasilkan daftar isi dari dan dengan mudah menghubungkan halaman. Kami juga menginginkan sesuatu yang dapat menghasilkan berbagai format dokumen termasuk HTML, PDF, dan ePub. Dokumen juga harus dapat dibaca di perangkat seluler.

@issafram Penurunan harga sangat bagus ketika dokumen Anda seratus halaman, kemungkinan besar lebih sedikit. Tapi ribuan halaman dan daftar isi yang saling terkait? Menjaga lampiran tetap up to date? Menautkan dokumen ASP.NET dan .NET? Ini akan menjadi berantakan.

Perlu diingat, jika Anda ingin ini benar-benar open source, dan dengan demikian sesuatu yang mendorong kontribusi, sistemnya harus sesederhana mungkin, tanpa kurva belajar. Penurunan harga tidak dapat menghasilkan ToC dengan sendirinya, tetapi kode yang relatif sederhana dapat menghasilkan ToC dari Penurunan Harga.
Kami di Orchard sangat senang dengan sistem kami, yaitu penurunan harga di Github ditambah situs Azure dengan kode yang sangat sedikit (untuk pengindeksan dan pencarian Lucene, ditambah pembuatan ToC) yang diperbarui secara otomatis setiap kali repo didorong. Alat yang sangat sederhana dan familier.
Satu-satunya hal yang saya tidak suka adalah kurangnya metadata (kami mengekstrak judul dari nama file), tetapi ada solusi untuk itu juga, seperti header YAML Jeckyll (didukung oleh Github) atau format Snippable saya sendiri.

@issafram Itu tidak bekerja dengan baik pada basis kode besar dengan BANYAK dokumen dan refactoring misalnya. Ganti nama kelas dan tautan relatif _bye bye_.

_edit_: Saya terlambat ke permainan :P

Saya senang mendengar bahwa dokumentasi ASP.NET akan menjadi ribuan halaman ;) Tetap saja, KISS.

@bleroy Lihatlah http://read-the-docs.readthedocs.org/en/latest/ ini dan rST yang membuatnya. https://github.com/rtfd/readthedocs.org/blob/master/docs/index.rst

Tentu, itu bagus. Hanya memberikan pengalaman kami. Saya mengerti Anda berada pada skala yang berbeda.

rST adalah pilihan terbaik di sini, langsung. Itu menjadi ASP.NET, memiliki sesuatu yang cukup pintar untuk memperbarui indeksnya (dari ToC atau bahkan sudut pandang daftar kelas) mungkin merupakan prioritas utama.

Idealnya saya akan menjalankan sesuatu di Build Workflow untuk mengambil semua file .XML yang dihasilkan dari binari dan kemudian menempatkannya melalui prosesor untuk menghasilkan file yang kemudian dipublikasikan ke server. Perkakas yang tepat.... Saya tidak tahu. Banyak yang telah disebutkan. Saya akan merekomendasikan membangun Anda sendiri dan open source itu. Ya ya... Debat build vs buy tapi saya benci menggunakan tools yang memiliki resource unmanaged seperti beberapa di atas. Anyways kedengarannya ideal ... Anda mungkin memiliki anggaran dan kendala waktu dan apa yang tidak.

@issafram Jika Anda semua akhirnya menggunakan Sphinx/RTD, sesuatu di sepanjang baris Breathe mungkin merupakan pendekatan yang bisa diterapkan: http://breathe.readthedocs.org/en/latest/ -- itu adalah integrasi dengan Sphinx & Doxygen yang menggunakan File XML Doksigen.

@issafram Kedengarannya Anda menggambarkan SHFB ... (Sebenarnya Sandcastle , SHFB hanya membuatnya lebih menyenangkan untuk digunakan :P )

Ya, Anda memerlukan preprocessor/postprocessor, Anda dapat menghubungkan relativitas dalam dokumen dengan GHMD untuk TOC. Untuk proyek kami, kami menggulung sendiri pada dasarnya mengambil .Net doc XML dan berbasis konvensi yang digabungkan dengan kode sampel & konten statis lainnya yang ditulis dalam MD. Hasil akhirnya adalah HTML.

Memiliki kode & konten statis editorial di MD akan memudahkan untuk melakukan PR. Apa yang saya suka tentang penurunan harga sebagai format sumber adalah bahwa itu lebih bersih daripada HTML, XML dll. Membuat audit menjadi mudah dan cocok untuk kontrol sumber.

Kami membutuhkan alat dokumentasi berbasis konvensi yang bersih dan sederhana untuk .Net, saya belum menemukannya, jika ada saya akan senang untuk diberitahu. Dan dengan senang hati akan berkontribusi untuk itu.

Adapun rawatan dan tautan antar proyek. Intersphinx adalah cara yang ampuh untuk melakukannya secara semantik. Ini memungkinkan Anda untuk membuat katalog semua referensi (baik itu kode atau prosa) dan menautkannya secara eksplisit di seluruh proyek.

Dokumen di sini: http://sphinx-doc.org/latest/ext/intersphinx.html

Ini adalah jenis fungsi yang tidak dimiliki sesuatu seperti Markdown dengan cara apa pun yang saya ketahui.

Setuju bahwa penurunan harga bukanlah solusi terbaik, tetapi untuk saat ini kami membutuhkan solusi sederhana. Ayolah kami adalah pengembang sehingga kami dapat memperluas ini jika diperlukan. Github mendukung penurunan harga, VSO sekarang baru-baru ini mendukung penurunan harga dari tampilan kode. Apakah kita benar-benar membutuhkan debat. Maaf jika saya terlalu langsung.

Penurunan harga +1

@ctsni Saya akui, penurunan harga _felt_ seperti pilihan terbaik pada pandangan pertama/pemikiran. Tetapi semakin saya memikirkannya, semakin terasa seperti kami mencoba memalu pasak persegi ke dalam lubang bundar.

Memang, saya tidak memiliki alternatif yang baik, jadi saya minta maaf karena sebenarnya tidak banyak berkontribusi, tetapi bahkan ketika memperpanjang penurunan harga, saya tidak _merasa_ kita akan berakhir dengan sesuatu yang sama dengan penurunan harga yang cantik, bersih, dan rapi seperti yang kita miliki sekarang _mengingat persyaratan_.

Sepertinya Anda ingin mereplikasi dokumentasi MSDN yang ada dalam format sumber terbuka? Apakah itu adil? Anda memerlukan solusi untuk menangani deskripsi ikhtisar, tutorial, contoh kode, dan dokumentasi API? Atau itu bagian dari itu?

Saya tidak yakin ada satu solusi, lebih banyak kumpulan alat yang outputnya dapat digabungkan. Saya dapat melihat apa yang dilakukan ReadTheDocs - menarik banyak sumber ke dalam satu set dokumentasi yang koheren. Jadi penurunan harga adalah jawaban yang valid untuk sebagian dari solusi (yaitu deskripsi dan tutorial), tetapi bukan gambaran lengkapnya?

Pertanyaan terbuka: Apakah mungkin mengekstrak lampiran dan TOC langsung dari penurunan harga? Sepertinya tidak terlalu sulit bagi saya? saya bias. Saya belum pernah mengerjakan sistem dengan ribuan halaman... Maaf @shanselman , saya benar-benar tidak dapat menyumbangkan kebijaksanaan di luar apa yang saya ketahui.

@craignicol Apa pun yang kurang dari dokumentasi MSDN saat ini, bagi saya, akan sangat mengecewakan. Saya selalu memberi tahu semua orang beberapa dokumentasi terbaik (dalam struktur, susunan kata, dan segala sesuatu tentangnya) ditemukan di MSDN. Saya telah melihat banyak dokumentasi tetapi sebagian besar, jika tidak semua, bahkan tidak mendekati "kualitas MSDN" (tentu saja IMHO). Karena itu: faktor besarnya adalah, tentu saja, orang-orang di balik dokumen MSDN sangat memperhatikan _konten_ MSDN yang sebenarnya; struktur, tata letak, desain, dan apa yang Anda miliki adalah yang kedua.

Mungkin tangensial, tetapi akan sangat menyenangkan memiliki sesuatu seperti dash . Pengembangan web berkembang begitu cepat dan teknologi baru saling mempengaruhi sehingga saya mencari informasi di sana-sini. Mampu mengakses semuanya di satu tempat yang dapat dipanggil melalui beberapa penekanan tombol, sangat membantu. Ada upaya serupa http://zealdocs.org/ untuk Linux dan Windows.

@craignicol Setuju, tujuannya adalah untuk memiliki dokumen kualitas MSDN yang open-source dan lebih mudah untuk mempertahankan dan tetap up to date.

@ciriarte Ada dukungan untuk menerjemahkan dokumen Sphinx ke Dash: https://pypi.python.org/pypi/doc2dash -- Kami telah melihat pembuatan set Dash otomatis di RTD.org, tetapi saat ini belum menerapkannya.

Saya pikir @shanselman meletakkan yang terbaik di atas - Penurunan harga bukanlah jawabannya selain HTML, Word, atau .txt akan menjadi jawabannya. Penurunan harga pada dasarnya adalah deskripsi presentasi - apa yang dibutuhkan adalah sesuatu untuk menghasilkan penurunan harga (atau HTML, dokumen Word, file .txt, dll.)

Saya kira pertanyaan saya adalah dari mana Anda melihat konten itu berasal? Apakah akan ditulis tangan? Dibuat otomatis dari kode? Disematkan dalam komentar?

Saya setuju dengan @craignicol kumpulan alat untuk menggabungkan konten yang dibuat secara otomatis dengan halaman GH Markdown "statis" untuk sampel buatan manusia dan konten editorial tidak tersedia dalam XML perakitan. Hasil keluar kemudian bisa berupa html statis di GHPages, PDF atau apa pun.
Preprocessor dapat mendeteksi konten statis yatim piatu jika kode diubah namanya/difaktorkan ulang Yaitu
Dukungan bahasa pada dasarnya dapat berupa folder opsional dengan struktur yang sama dengan netral. Dokumen yang tidak diterjemahkan kemudian dapat mundur ke netral atau melalui terjemahan Bing.

Melihat kembali saran asli akan setuju dengan @ danroth27 tentang penurunan harga untuk format dan readthedocs untuk build. Terima kasih.

Fleksibilitas readthedocs.org + Sphinx dapat memungkinkan kesetaraan dengan MSDN, jika tidak dapat didekati.

@ciriarte Itu mungkin dapat didukung juga dengan arsip yang dapat diekspor untuk pembaca MSDN.

@jalcine @ericholscher terdengar fantastis.

@RobThree Saya harap tim yang saat ini memelihara dokumen dapat dibujuk untuk pindah ke format baru, jika tidak, latihan ini tidak layak dilakukan.

@ctsni itu mungkin - Saya telah menulis parser ToC penurunan harga dengan python, yang mengambil daftar file dan menghasilkan ToC. Bagian yang sulit adalah membuat anotasi pada file sumber sehingga parser mengetahui apa yang harus diekstrak untuk menghasilkan ToC dan lampiran. Format perantara, apakah penurunan harga atau rST, tidak relevan, itu adalah kuncinya untuk mendapatkan metadata dengan benar.

Melihat dokumen MSDN, dua bagian kunci metadata yang paling penting untuk hyperlink adalah kait API, untuk memungkinkan traversal kode, dan kait konseptual (misalnya Keamanan) yang membuat topik untuk mencakup API, tutorial, dan informasi arsitektur. Jika bagian API dilakukan dengan benar, saya yakin konten lainnya dapat disesuaikan. Saya menyukai ide Dash, tetapi saya pikir ReadTheDocs dan Sphinx adalah yang paling dekat dengan apa yang saya suka tentang MSDN, tetapi saya pikir mereka perlu disesuaikan untuk menangani topik yang kaya dan struktur tutorial yang dimiliki MSDN.

Saya bertanya-tanya tentang seluruh konsep ini. Maksud saya, saya menyukai gagasan untuk membuka sumber rantai dokumentasi dan melibatkan komunitas tetapi melakukannya di luar jenis MSDN memberi saya kemauan. Dari apa yang tampak seperti (dan mungkin telah) awal .NET kami telah pergi ke MSDN untuk referensi kanonik pada Microsoft API apa pun. Dari WinForms hingga WebForms semuanya ada di satu tempat, direferensikan dengan baik dan diformat secara konsisten. Mau tak mau saya bertanya-tanya apakah yang diperoleh dari upaya ini akan memberikan manfaat yang cukup untuk mengatasi fragmentasi dan hilangnya konsistensi. Tidak mengatakan itu tidak akan benar-benar layak, dan mungkin diskusi ini telah terjadi, tetapi bahan untuk dipikirkan.

+1 untuk Sphinx

Saya benar-benar menggali format dan alat readthedocs dan mereka bekerja dengan sangat baik untuk banyak proyek. Jangan menemukan kembali roda. Penurunan harga baik-baik saja. Saya pikir jika Anda tidak dapat menggambarkannya dengan penurunan harga, maka Anda mencoba melakukan sesuatu yang terlalu rumit. I untuk satu akan senang untuk berkontribusi jika format dan tingkat gesekan rendah. Wiki MSDN sedang menuju ke sana, tetapi sebagian besar ditutup dan menjadi gurun tandus dari konten lama. Komunitas PHP tampaknya melakukannya dengan cukup baik dengan sistem dokumen mereka (walaupun komentar mereka terkadang gagal). Saya pikir menjaganya tetap sederhana dengan penurunan harga akan berhasil, tetapi mungkin perlu ada semacam alat pengindeksan/generasi untuk "dokumen master" atau sesuatu untuk menyatukannya dan menjaganya tetap sinkron. Hampir seperti sistem pembangunan ketergantungan untuk ribuan cuplikan/dokumen penurunan harga.

Saya pikir Penurunan harga untuk fragmen teks. File front-matter atau json Yaml untuk meta-data. Prosesor berbasis .NET kustom dengan model plugin yang dapat diperluas untuk dengan mudah menambahkan sintaks untuk hal-hal mewah seperti TOC dan tabel dll. Atau cukup gunakan terlebih dahulu, cukup mirip dengan Penurunan harga.

Buat saja MSDN Open Source. Kecuali itu berantakan :)

@somedave tidak tahu tentang Anda, tetapi saya semakin sulit menemukan konten di MSDN, terutama dokumentasi arsitektur tingkat tinggi pada kerangka kerja non-saat ini. Memiliki dokumentasi yang ditautkan ke kode, dan semua sumber terbuka yang tersedia dan di bawah kendali versi adalah peningkatan besar.

Apakah kita benar-benar menginginkan MDSN lain dari Microsoft baru? Banyak dari dokumentasi yang dihasilkan adalah buang-buang waktu. Yang dibutuhkan adalah narasi dan contoh, tetapi seringkali hal ini hilang sehingga hanya menyisakan info dasar yang sudah saya miliki dari sistem tipe. Dengan akses mudah ke sumbernya, sekarang kita dapat mengetahui apa yang sebenarnya dilakukan sesuatu. Artikel, penjelasan, dan contoh pengujian penggunaan jauh lebih baik terutama jika dibuat sebagai tanggapan atas permintaan, misalnya pertanyaan Stack overflow.

@danroth27 , apakah Anda berbicara murni tentang dokumentasi javadoc/xmldoc, atau juga dokumentasi secara umum? Yaitu 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

Jelas HTML tetapi dengan kemampuan untuk menggunakannya secara lokal - katakanlah untuk menginstalnya di IIS lokal (atau hanya secara lokal).

Silakan membangun saluran Sandcastle dan SHFB dan membantu membuatnya lebih baik (lebih sederhana dan 'ramah open source'). Dukungan untuk authoring penurunan harga (untuk konten konseptual) dan rendering dapat ditambahkan (beberapa permulaan telah dibuat ke arah ini).
Ada banyak nilai dogfood dalam mendukung alat berbasis .NET yang populer (setengah juta unduhan untuk SHFB). Idiom memang bocor dari alat ke dalam proyek itu sendiri. Misalnya, dengan .NET, sangat berharga untuk mendukung cuplikan kode multi-bahasa, sehingga VB.NET dan F# dapat dipertahankan sebagai bahasa yang layak di platform. Sandcastle dan keluaran gaya MSDN melakukan ini dengan sangat baik.

Masalahnya dengan reStructuredText adalah seperti penurunan harga, tetapi tidak sepenuhnya. Dengan demikian menjadi format lain untuk belajar. SHFB saat ini menyelesaikan pekerjaannya, tetapi ini bukan pengalaman yang menyenangkan. Sesuatu lebih baik daripada tidak sama sekali dan EWoodruff mengucapkan terima kasih yang tak terhingga untuk menjaga ini tetap hidup dan diperbarui begitu lama.

Dari sudut pandang pengembang .NET, alat pembuatan dokumen opensource yang sangat bagus untuk .NET masih dibutuhkan / diinginkan. Menurut pendapat saya lebih disukai alat yang memungkinkan teks bentuk panjang untuk ditulis dengan penurunan harga karena itu adalah sesuatu yang diketahui dan menyenangkan untuk digunakan.

Saya tahu tim MS mungkin ingin mendapatkan sesuatu dan menjalankan untuk mengirimkan asp.net 5 keluar dari pintu, tetapi ini menyentuh rasa sakit yang sudah lama dirasakan oleh pengembang.

Salah satu saran saya adalah bekerja dengan http://commonmark.org/ untuk mengembangkan modul commonmark dan melihat peningkatan sesuatu seperti https://github.com/Knagis/CommonMark.NET.

Jika tidak, setidaknya terbuka untuk mengganti sistem dokumen setelah rilis pertama sehingga komunitas tidak terjebak dengan sesuatu yang memiliki banyak gesekan untuk digunakan.. lagi.

Juga titik rasa sakit lainnya. Dokumen harus tersedia dalam beberapa format yang dapat digunakan secara lokal. Ada orang yang bekerja pada sistem yang tidak terhubung ke internet dan dokumentasi offline adalah penyelamat. Saya harus bekerja di lingkungan seperti itu dan dokumentasi offline sangat berharga.

@ryanbnl Kami mencari solusi untuk dokumentasi referensi API dan konten konseptual.

@michaelherndon Saya sepenuhnya setuju bahwa ada kebutuhan untuk alat pembuat dokumen open source yang bagus untuk .NET! Anda juga benar bahwa kami perlu menyiapkan dan menjalankan sesuatu dengan cepat untuk ASP.NET. Jika dokumentasi berbasis .NET yang didukung komunitas muncul, kami tentu saja terbuka untuk mengadopsinya. Kami juga setuju bahwa memiliki cara untuk mengakses dokumentasi secara offline adalah suatu keharusan.

Oke, sudah jelas :) Untuk dokumen API, ada baiknya melihat doxygen. Ini sangat kuat, dan dapat menghasilkan diagram kelas (yang dapat sangat berharga dalam situasi tertentu). Saya membuat perbandingan rinci dari doxygen/sandcastle tahun lalu, saya dapat mengirimkan salinan jika itu akan membantu? Ini berisi banyak contoh + panduan pemasangan langkah demi langkah (doksigen sulit dipasang) ;)

Sepertinya satu masalah adalah menjaga dokumentasi tetap open source sehingga orang lain dapat berkontribusi. Kedua adalah alat yang digunakan untuk memproduksi dan memelihara dokumentasi tersebut.
Bisakah kita tidak memiliki alat yang open source dan memungkinkan html/GHMD dihasilkan untuk unggahan akhir. Siapa pun yang perlu berkontribusi dapat menggunakan alat ini dan memodifikasi halaman berdasarkan tingkat akses mereka di github. Alat harus fleksibel sehingga dapat digunakan untuk proyek kecil atau besar. Alat ini dapat berupa ekstensi VS yang menghasilkan dokumentasi untuk proyek apa pun dan contoh dokumentasi untuk template dasar dapat bersifat opsional seperti opsi autentikasi saat ini dalam proyek baru.

@farrukhsubhani alat mungkin tidak bergantung pada VS: jika kita ingin pengguna Mac dan Linux menggunakan dan berkontribusi ke ASP.NET, alat harus lintas platform dan tidak memerlukan instalasi besar.

Saya perhatikan ada sangat sedikit komentar dokumentasi di sumber sekarang. meskipun bervariasi dari file ke file. Apakah sudah ada keputusan untuk menggunakan itu sebagai masukan untuk dokumen referensi, atau terserah pengembang individu?

Apapun hasil diskusi ini, saya ingin berbicara mendukung setidaknya memiliki itu di masa depan, dengan dukungan kompiler untuk membuat file XML tersebut (atau format lain yang dihubungkan ke IntelliSense) dan pengalaman pengeditan dan penyorotan hari ini yang sangat lucu dengan Roslyn di Visual Studio.

Mungkin orang lain sangat tidak setuju, tetapi saya sangat tidak suka mengedit /* */ komentar gaya untuk itu dan serangkaian * yang selaras. Tolong beri tahu saya bahwa saya tidak perlu khawatir;)

@danroth27

Hanya beberapa pemikiran dan terima kasih sebelumnya untuk setidaknya membaca dan memikirkan hal ini.

Teks yang direstrukturisasi sepertinya PITA untuk menyuntikkan hal-hal sederhana seperti tautan atau judul. Saya akan mengambil komentar kode Javadoc atau hanya Vanilla html selama ini setiap hari dalam seminggu.

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

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

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

check out the _aspnet homepage.

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

Saya ingin meminta agar aspnet mendiskusikan secara internal bekerja dengan komunitas dalam menetapkan beberapa tujuan / spesifikasi pada alat dokumentasi .net dan mungkin memberikan beberapa insentif kreatif seperti pengakuan atau sesuatu seperti itu. Saya juga meminta Anda semua untuk mendiskusikan pengaturan proyek melalui yayasan .NET. Ini juga bisa berfungsi sebagai proyek magang/musim panas kode yang layak untuk dikerjakan oleh siswa cs karena kemungkinan besar akan melibatkan pembuatan parser.

Ini tidak ditujukan kepada Anda atau siapa pun secara khusus, tetapi sudah terlambat dalam siklus dev untuk sekarang mulai memposting dan memikirkan hal ini karena memaksa kalian ke sudut untuk menggunakan sesuatu yang berfungsi, tetapi bukan sesuatu yang hits semua skenario termasuk hambatan masuk yang rendah.

Secara hipotesis, berbicara dengan komunitas sebelumnya mungkin setidaknya menghasilkan alat sekarang yang akan dapat digunakan dan itu bisa dibangun secara paralel di atas semua kerja keras tim aspnet sebagai contoh yang baik dari aspnet dogfooding 5.

Yang sedang berkata, jika ini dimulai sekarang, itu bisa siap untuk mengatakan .NET core 5 untuk digunakan.

@ericwj semua API publik diperlukan ¹ untuk memiliki komentar dokumen XML pada mereka. Namun, di awal proyek kami melonggarkan persyaratan itu karena menulis banyak dokumen di API yang kami tahu akan berubah secara signifikan dianggap sebagai upaya yang sia-sia. Namun, dalam semua komitmen dari beberapa bulan terakhir harus ada sejumlah besar dokumentasi yang ada. Memang masih banyak lubang, tapi sudah menjadi kewajiban tim untuk menyediakan dokumentasi ini. Saat menambal dokumen, kami cenderung berfokus pada API yang lebih penting yang menurut kami akan diakses oleh pengembang, dan menurunkan lebih banyak API esoteris ke status yang kurang terdokumentasi (yang masih kami harapkan untuk diisi suatu hari nanti).

¹ diperlukan _adjective_

Sesuatu yang tidak opsional.
Bisa juga berarti sesuatu yang _is_ opsional dalam konteks komentar dokumen XML.

@michaelherndon BTW proyek ini sudah menjadi bagian dari .NET Foundation .

@Eilon konteksnya berbicara tentang menambahkan alat dokumentasi .net, bukan aspnet 5.

@michaelherndon ah mengerti, terima kasih!

@shanselman @danroth27 , saya telah memberi tahu Jumat lalu manajer saya dan yang ini telah menghubungi PM Grup Utama MSDN tentang utas itu. Mereka harus menghubungi Anda tentang masalah dokumentasi Anda. Semoga harimu menyenangkan.

@michaelherndon Saya setuju bahwa sintaks header sedikit lebih verbose. Kasus umum lainnya adalah menautkan ke suatu fungsi, atau halaman dalam dokumentasi, di situlah RST bersinar:

More Info
=========

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

Melakukan sesuatu yang serupa di 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).

Saya tidak melihat perbedaan mendasar yang besar di sini. RST dengan Sphinx memberi Anda beragam fungsi referensi berharga yang akan hilang, atau ditautkan secara non-semantik ke URL atau dokumen HTML dalam kasus Penurunan Harga.

Berita gembira lain yang menarik di sepanjang baris ini adalah dokumen ini tentang cara menulis RST dan MD dengan cara yang kompatibel: https://Gist.github.com/dupuy/1855764 . Penurunan harga umumnya mendukung tajuk gaya RST, sehingga gaya tajuk akan berfungsi di keduanya.

Anda juga dapat mengonfigurasi Sphinx atau alat lain untuk memahami sintaks penurunan harga dasar dengan ekstensi jika itu adalah penghenti acara.

Saya ingat mengatakan di panel OSS di MVP Kirim sekitar 18 bulan yang lalu bahwa tidak ada pilihan yang baik untuk dokumentasi di .NET :stuck_out_tongue_closed_eyes:

Apa yang benar-benar ingin saya lihat adalah cara untuk menghasilkan penurunan harga atau yang pertama ditambah daftar isi dari dokumentasi XML .NET. Itu kemudian dapat dimuat ke dalam sesuatu seperti readthedocs atau github wiki.

Sandcastle sudah memiliki banyak kode untuk membaca dokumentasi XML .NET dan dapat diperluas dengan gaya dan tipe keluaran baru. Anda bisa membangun itu.

Bagaimana saya melihat utas ini dan mencari tahu apa kesimpulannya, apakah keputusan telah dibuat, dan jika ya, apa itu?

https://github.com/aspnet/Docs

Mengapa kalian tidak menggunakan DocFX?

Ketika kami mulai menulis dokumentasi untuk ASP.NET 5, proyek docfx masih dalam tahap awal pengembangan. Sphinx masih merupakan kerangka kerja dokumentasi yang jauh lebih matang dan kaya fitur. Selain itu, Read the Docs menawarkan solusi hosting dokumentasi yang sangat bagus.

Karena itu, kami mendukung upaya docfx sebagai solusi dokumentasi untuk .NET dan sangat menarik untuk melihat bahwa docfx sekarang open source! Kami sudah berencana untuk menggunakan docfx untuk dokumentasi referensi API dan kami berharap untuk pindah ke docfx saat sudah matang.

Sepertinya memalukan untuk pergi dua arah yang berbeda keluar dari gerbang ketika docfx tampaknya menjadi apa yang digunakan MSDN, setidaknya mengikuti tema bawaan.

@simonmurdock docfx tidak (belum) mendukung pembuatan dokumen offline, seperti PDF

Ya @cocowalla saya selalu berubah-ubah tentang keadaan penyatuan dengan dokumentasi. Saya sekarang menulis artikel saya di sphinx, tetapi tidak ada cara yang bagus untuk membuat dokumen API terintegrasi sphinx.

Rencana saat ini adalah Sphinx untuk semua artikel dan situs terpisah untuk keluaran DocFX, hingga Sphinx ApiDocs terlihat sedikit lebih bagus.

@simonmurdock Inilah yang saat ini kami lakukan untuk menghasilkan dokumen referensi API untuk ASP.NET menggunakan kombinasi docfx dan ekstensi autoapi Sphinx: https://github.com/aspnet/apidocs. Ini masih agak kasar, tetapi kami bekerja dengan orang-orang Baca Dokumen dalam banyak peningkatan.

@danroth27 Begitu banyak suara untuk RST, namun, akhirnya Anda memilih MD? Ketika saya mengklik EDIT pada halaman mana pun di https://docs.microsoft.com/en-us/aspnet/core/ , saya melihat file sumber MD di GitHub.
Jadi kenapa MD?

Kami menggunakan RST dan http://readthedocs.com untuk sementara waktu untuk dokumen ASP.NET Core dan EF Core, tetapi baru-baru ini Microsoft membangun infrastruktur dokumennya sendiri di http://docs.microsoft.com , jadi kami pindah ke sejajar dengan itu. Meskipun penurunan harga bukanlah bahasa dokumentasi yang matang seperti reStructuredText, ini lebih akrab bagi audiens yang lebih luas. Bahkan Read the Docs mendukung kedua format karena alasan ini.

@ danroth27 Apakah itu berarti Microsoft telah membuat generator/mesin dokumentasi non-open source sendiri yang menggunakan penurunan harga? Apa yang tertinggal di balik https://docs.microsoft.com?

Apakah itu berarti Microsoft telah membuat generator/mesin dokumentasi non-open source sendiri yang menggunakan penurunan harga?

Tidak. Mesin dokumen di balik https://docs.microsoft.com adalah DocFX dan dibangun di atas .NET dan sepenuhnya open source. Itu memang menggunakan penurunan harga untuk formatnya.

Hai

Mungkin saya agak telat memposting ini.

Saya hanya ingin tahu apakah ada api atau kerangka kerja atau alat yang memungkinkan kami membuat situs dokumentasi seperti yang untuk https://docs.microsoft.com? Saya pribadi suka bagaimana dokumentasi microsoft disajikan, @danroth27 menyebutkan DocFX yang merupakan mesin yang digunakan, saya hanya ingin tahu apakah situs itu sendiri adalah sesuatu yang dilakukan dari bawah ke atas atau apakah ada template atau paket yang kami dapat gunakan untuk menghasilkan tampilan dan nuansa yang sama? tidak persis sama tapi sesuatu yang bisa kita modifikasi :)

Terima kasih!
Yudas Alquiza.

Semakin banyak saya membaca tentang DocFx , semakin saya menyukainya - akan segera mencobanya.

Bagaimana kami dapat membuat situs web dokumentasi kami sendiri seperti https://docs.microsoft.com/ secara internal tanpa menciptakan kembali roda? Kami menggunakan readthedocs yang dihosting untuk dokumen python dan doxygen yang dihosting untuk dokumen c/c++.

Apa cara terbaik untuk mendapatkan semua dokumen API di bawah satu atap? Dari membaca utas ini, tampaknya banyak orang menggunakan sphinx/readthedocs tetapi bagaimana Anda mengonversi dokumentasi .XML Anda ke format yang tepat untuk alat ini?