Would a ReadTheDocs site be interesting?

[tillig]

The README is getting to be pretty long and I noticed that a lot of questions I've seen come up in the issues list might be self-answered if there was a more dedicated documentation site like something hosted on readthedocs.io. A site like that could be easier to search and navigate, and tying it into the build would mean if you need to update docs it'd be just as simple as committing a change to the README like it is now.

If it would be interesting, I'd be happy to set up a pull request with a base configuration for the docs and start moving some of the README content over. The only thing you'd have to do is follow their guide to sign up for an account and attach the repo so they can start building on each commit. (You need to do that so you own it.)

After that, any time you need to update your doc site, you just update the restructuredText in the docs and commit. It's pretty simple; I run the doc site for Autofac and write most of that doc, too, if you want an example.

[domaindrivendev]

@tillig - is this still something you would be willing to assist with?

[tillig]

Yeah, I could still help you set that up.

What I need from you to get that going:

• Create a repo for your docs.
• Get an account with RTD so you're ready to attach the repo once there are some docs.
• Tell me a little bit about how you want things generally organized in the docs (more on this in a second).

That shouldn't take too much. After that, I can set everything up and submit a PR to that repo with a base set of docs that can be enhanced over time.

Finally, once that PR is in, you can attach it to RTD and it should start building. (You can't attach an empty repo... I don't think...)

On the organization of the info: It's good to get at least a general organization of the docs right up front because people will paste the URLs into StackOverflow questions and so forth. Adding pages isn't too big of a deal, major reorgs break things.

Assuming the docs will basically cover what is going on with this repo (the .NET Core version, not the older Web API version), I'm thinking a decent layout might be...

• Getting Started
• About Swagger (explain the relationship of Swashbuckle to Swagger, Swagger UI, etc.)
• Routing
• Configuration
  • Swagger Endpoints
  • Swagger UI Properties (doc title, parameters)
  • Pretty-Print Swagger JSON
  • Omit Obsolete Operations
  • XML Documentation Comments
• Extensibility
  • Operation Filters
  • Schema Filters
  • Document Filters
• Cookbook
  • Omit Arbitrary Operations
  • Enable OAuth 2.0 Support

That's not complete with all the stuff in the README but you get the idea - explain the actual configuration options, explain the extensibility options, and then have a cookbook or FAQ section to describe commonly used tasks that take advantage of config and/or extensibility available.

Does that look reasonable?

If so, set up the repo and let me know where it is. I'll get working on the PR for an initial doc set when that's available.

[domaindrivendev]

@tillig - just getting back around this, and sincere apologies for the delay. Is it still something you could put some time towards? I setup the RTD account and webhook from GitHub. I also created a branch - readthedocs with the initial sphinx setup and pointed RTD to that branch. I could give you push access to it so your updates will be automatically generated at https://swashbuckleaspnetcore.readthedocs.io/en/latest/, if you had some time to get the docs started?

You had suggested a separate repo for the docs. I think I'd prefer to keep the docs and code together - as they typically change together, and I like the idea of having all the work for a releasable feature incorporate into a single PR. Do people do it this way, or is the separatete repo pretty much the de facto approach?

[tillig]

I'm not sure I'll have a ton of time anymore, to be honest. I was in the thick of working with Swashbuckle stuff and able to help out back in June of last year when I first offered to get things going; and was largely in the tail end of that project in June this year but still able to throw some time at it. Since June my project focus has changed and I'm working on a lot more infrastructure-y things rather than any app coding so that plus approaching holiday/end of year will limit me.

However, I could still probably set up at least a base framework and get things moving even if I can't write everything up.

I had suggested a separate repo for the docs for a couple of reasons:

• If you maintain your docs in the same repo but on a separate branch, the code will change at a different rate than the docs anyway because the branches are split and nary the twain shall meet.
• If you maintain your docs in the same repo on the same branch as the code, then every code change or doc change will build the whole thing, which sucks.

If you maintain your docs in a separate repo, you get a few benefits:

• It's easier for people to figure out how to make pull requests to the docs. The separate branch thing gets confusing.
• You can use branches to manage upcoming large doc changes.
• You can use tags [that don't interfere with the code] to indicate doc versions.

I found ReadTheDocs was definitely more geared toward having everything in a dedicated repo. Path of least resistance sorts of things.

But, you know, it's your project and it's definitely up to you how you want to do it.

I'd be happy to push some basic stuff in there to help out. I did see the invite to collaborate come through in email but logging into GitHub it appears to have been lost/revoked. I'm guessing you were still in the process of setting things up. I could also just PR things into place if that's better. Whatever works.

[domaindrivendev]

@tillig - totally get it. Any help would be appreciated (even if it's just getting the existing docs mapped over) but I also understand how it goes with earning a living vs spending time on OSS. So, if you can absorb a little bit of work - great, if not that's fine too.

If you do find some time, let's got with the PR approach for now?

Regarding the same vs separate repo, I'd like to try it out from this one for now. While I did setup an initial branch for getting things setup - I would ultimately keep the docs in the same branch as the code. So, some of the cons you mentioned above wouldn't be applicable. I could live with the rebuilding on every push (this happens for Nuget's today and hasn't presented any issue for me). Or better still, if I could limit it to only happen for certain tags (i.e. major version increments) - it looked like this may have been an option in some of the advanced RTD settings.

We could start with this approach anyway, and if things get difficult, then we can look at moving to a separate repo?

[domaindrivendev]

@tillig - interested to know if you've started any work on this yet. I have a little bit of time to put into it, so if you haven't started yet, I can get things kicked off. Let me know?

[tillig]

I haven't started anything, sorry. Go for it.