Add generated documentation site #218
Conversation
This change introduces a new documentation site for the PowerShell Editor Services project. It uses the DocFX tool to generate both conceptual and API documentation pages. The conceptual documentation pages come from Markdown files in the docs folder. The API documentation pages are generated dynamically from the XML documentations in the C# classes of the main .NET DLL of the project. A script called BuildDocs.ps1 is included to handle the generation and publishing of the documentation site.
|
Link to the generated docs for preview? |
|
https://powershell.github.io/PowerShellEditorServices, let me know what you think! |
|
Reading through now, first impression is good - I wish there was a way to have the "Improve this page" link take you straight to the editing of that page, but one extra click is no problem. :) Will update once I've reviewed the actual docs. |
|
It's strange that DocFX doesn't link directly to that since they easily could. |
|
Specifically regarding the Using the Host Process page, how much of the text here was composed for human consumption? There does seem to be some sections with text targeted at a reader vs literal documentation of the JSON objects, but much of it seems to be "This exists and has these properties" which is an absolutely necessary step one. Extending the Host Editor seems like a much more robust doc of the Guide category than the previous - it includes examples and reasoning pretty frequently. Reviewing the API docs themselves now. Disclaimer: I'm looking at the docs quickly for first impressions, not the required serious review for actual constructive feedback. Edit: A word. |
|
The host process page is way out of date, I need to go back and revamp that completely. There's a warning at the top of the page to make sure people don't follow it too closely. Once I redo it I'll explain all of the message types thoroughly. The "Extending the Host Editor" page is a much better example of what I hope to do going forward. The API doc pages still need some work and we'll probably need to improve our code documentation so that those docs turn out right. I appreciate your time looking at these! |
|
Specifically looking at the EditorSession class: I love that I can click the type of a property and have it link to the documentation for that type. I was about to complain about this when I realized the table beneath the declaration contains the link. The documentation of the properties and methods themselves is okay with the exception of wanting a few things that would probably be terribly cluttered to include in the code:
The class I picked to look at first might not have been a good example for this because it seems pretty straightforward, but those are the two things that I typically am leery of when it comes to code-generated documentation. What are your thoughts? My point of view is mostly as a consumer of these types of docs rather than a writer of the code behind them. Also, I'm glad to take a look at documentation and provide feedback, especially since I use the software and don't contribute code. :) |
|
We definitely need code examples in the API docs. It seems that DocFX gives me the ability to write supplemental Markdown-based documentation for any class or method in the API docs. I might try experimenting with that once I have some more time to look at it. You're also right that some methods need more explanation, especially around error cases. I was expecting that generating doc pages from the API docs would expose this need. I still need to figure out the best patterns for documenting C# APIs. I'll be spending more time on this once the API becomes more stable and we prepare for a 1.0 release. |
|
As long as there's a way to add the documentation without cluttering the C# code itself, this seems like a good tool. The aesthetics of the generated site are fantastic. My experience with API docs most recently has been influenced by the ElasticSearch docs, which are much more prose-y than I believe most docs are. That does make them very usable but does presumably cost a lot of resources for writing and upkeep. |
This change introduces a new documentation site for the PowerShell Editor
Services project. It uses the DocFX tool to generate both conceptual and
API documentation pages. The conceptual documentation pages come from
Markdown files in the docs folder. The API documentation pages are
generated dynamically from the XML documentations in the C# classes of the
main .NET DLL of the project.
A script called BuildDocs.ps1 is included to handle the generation and
publishing of the documentation site.
This change is