Sounds good! I'll try and make a start on some of these tonight.

What are your thoughts about using a sample project to illustrate the code samples, and then bring in the code samples into the docs via Sphinx's literalinclude functionality?

You can see this in action on the ASP.NET docs

Source - https://raw.githubusercontent.com/aspnet/Docs/master/aspnet/tutorials/your-first-aspnet-application.rst
In Action - http://aspnet.readthedocs.org/en/latest/tutorials/your-first-aspnet-application.html

That way the samples more or less get compiled with the build (assuming the sample project is included in the build process, of course). Coding style and standards could also be easily enforced. Plus it'd give people a chance to open the project and run through all the examples. I figure people will probably be writing their sample code in Visual Studio regardless - this just saves them from having to create their own project for copying and pasting.

The downside is I don't think markdown supports this. I've always used reStructuredText with Sphinx myself, so I'm pretty comfortable with it but I could see it being a an initial blocker to people contributing.

Hey @enkafan

That sounds pretty cool actually. I don't mind switching to rst, I haven't used it myself but if you wanted to submit a PR which switches it I am happy to go down that road. I don't think it will be a blocker to contributing as there are examples to follow.

Issued a pull request (#316) with a quick redo to Sphinx. I included a contributing page pulled from the ASP.NET groups contributing page to include steps on running sphinx on your local box plus the style guidelines they recommend.

Was about to jump in and try and help but it looks as though we need PR #316 to be merged before starting. It looks as though reStructuredText is now the preferred format.

@billglover merged now :) sorry about that

Hey all,

I have put some new docs infrastructure in place which makes all this quite nice. Help on finishing this off would be awesome :)

I've started working on this, however I'm noticing that my new assertions aren't appearing within the navigation of other assertion doc files (ie: _build/html/assertions/shouldMatchApproved.html). I've added the assertion to the index.rst file (I see you did the same thing when updating the docs); do you have any ideas what I could be missing?

Make sure you delete your local _build folder and rebuild. I have noticed it doesn't always rebuild the TOC

Alright, thanks Jake. I'll give that a try.

Finally got around to trying it and that was the issue, you've got to delete the _build folder and rebuild (for anyone else who experiences the same issue!)

@JakeGinnivan - Is the list at the top of the issue still current for what needs converting? Been looking for a project to get involved with, and this seems like a good place to jump in.

Hi @mwhitis Yes, the list is still up to date. Help with the docs would be very much appreciated!

i'm a little new, so pardon my question, but does this just involve taking a topic and reformatting it to fit the doc format of this repo?

Hi @morrme

Yes it does, though we have some means of auto generating the code samples. This pull request will give you an idea of what's involved.

If you have any questions then do ask :)

@josephwoodward took me a while to find this issue again!

So are the generators written by hand based on the current samples?

Is this still an open issue? If so, I'd love to help out.

Yes it is still an issue, there's soooo much migration to do :S

Hey Joseph,

Sorry for the wait in responding. I'll try to set aside some time this weekend. It's been hectic at work. I'll let you know once I get set up and everything.

@josephwoodward I sent you an email regarding an issue. Can you see if you got it?

I can see that this issue is still open, and that there's a ton left to do, but I honestly can't figure out what it is that needs to be done. I would like to help, so if anyone could explain to me what needs to be done, that would be great.

Is it just a matter of copying the content on the old docs site to the new docs site (readthedocs.org), or is there more involved?

@josephwoodward in an earlier comment, you referenced a pull request as being indicative of what this task involves, but I didn't understand even after taking a look at it...

Yeah, this is something I'd really like to finish soon. I'll need to refresh my memory on how to do it first, I also wonder whether there's a Docker container to help with setting up a local environment.

Yes it does, though we have some means of auto generating the code samples. This pull request will give you an idea of what's involved.

Hi, I just found this issue and I'm a bit confused. The changes referred to in the comment above refer to a commit where next to documentation also code changes were done. Is this issue only about migrating the documentation or is this some sort of a migration of the code too? And if so, where can we find the old codebase?

@jnm2 @josephwoodward ok i made a fair dint on the usages snippets and the resulting exception. see update list above. changes have been deployed to the docs site.

@jnm2 @josephwoodward ok i made a fair dint on the usages snippets and the resulting exception. see update list above. changes have been deployed to the docs site.

Oh nice! Thanks!

ok this is done. let me know if i missed anything

@SimonCropp You're a legend!