New Documentation System powered by MkDocs and ReadTheDocs #431
Conversation
Prototyping documentation layout for generating a ReadTheDocs site.
- MethodAuthorization progress - Changes to the supplemental CSS to better format <code> tags.
- Release notes updates - More realistic Filters examples
- Temporal Type adjustments - Contribution Guidelines - Method authorization tightening - Interceptors scaffolding
- Interceptors example - New Method Authorization section on using both techniques at once.
|
Hi @advancedrei, I'm your friendly neighborhood Microsoft Pull Request Bot (You can call me MSBOT). Thanks for your contribution! The agreement was validated by Microsoft and real humans are currently evaluating your PR. TTYL, MSBOT; |
|
I have seen the PR, we have China Dragon Boat Festival now, I will add comments when I am back to office on Monday. |
|
No worries, have fun at the festival! Looking forward to your thoughts :) I will be working more with RESTier throughout the weekend, so I may push some more documentation updates before then. |
docs/clients/dot-net.md
Outdated
| mkdocs.yml # The configuration file. | ||
| docs/ | ||
| index.md # The documentation homepage. | ||
| ... # Other markdown pages, images and other files. |
There was a problem hiding this comment.
Seems a place hold now.
There was a problem hiding this comment.
Yes, this is just a placeholder for now, just so the item shows up in the Table of Contents. I will make sure to change it so that it just says something like [THIS IS A PLACEHOLDER FOR FUTURE CONTENT]
- Updates still in progress. - Also removing placeholder content on other pages.
| pages: | ||
| - Home: | ||
| - 'Introduction': 'index.md' | ||
| - 'Getting Started': 'getting-started.md' |
There was a problem hiding this comment.
How you think about section header like
- Introduction
- Getting Started
- Building the Services
3.1 Entity Set Filters
There was a problem hiding this comment.
I took the numbers out because the ASP.NET team doesn't use them, and the documentation needs to be fairly consistent across the total API surface. Plus, numbers are just one more thing you have to keep up with changing as the docs evolve and new sections are added. I just don't think the benefit is worth the effort.
There was a problem hiding this comment.
I was thinking number is better to reference like tell people which section, record note with section and so on.
If practice already shows not too much benefit, I am OK now.
|
Just for anyone who can merge PR, we need to pass OSS process for mkdocs tool and readthedocs.io site before we can merge this PR per discussion with Mark. I will initiate this process with help from Mark. |
|
OSS for mkdocs has been done. Relevant link |
|
Yay! What's the ETA on readthedocs? |
|
We do not have a ETA yet, we have contacted our domain name management team and share asp .net document information with them, and they will help to contact asp .net team and see what we need to do, then we may get a target date, we will share status here. In the meanwhile, we can work on the document content and when the process is done, we can push first version of document. @jmxz will help on the document if you need us to own some part. |
|
I don't think this one is going to go anywhere. I'm going to close it for now so I can work on other things. We'll revisit at another time, and I'll link the new PR then. |
Issues
This pull request begins to fix issue #418.
Description
This changes the way documentation is organized and compiled to provide an experience nearly identical to the ASP.NET Documentation site. The future documentation home may reside at http://docs.restier.io as discussed in yesterday's conference call.
Additional work necessary
PS: I tried to squash this commit down into 1 clean commit, but I clearly didn't do it right. Hopefully you all are better at Git than I am. :)
Thanks!