What needs to be done, post here if you are picking up a topic. I will put your name next to the task, please try and submit a pull request soon after so the task does not get blocked. If you cannot complete your task, let me know and I can remove you!
Current docs are at http://docs.shouldly-lib.net/v2.4.0 - some docs are missing, others out of date. Once the section has been created in the new docs, I will delete it out of the current docs site. If you notice I have missed something, yell out!
The docs are in the docs folder in the repository, so just submit a pull request. For new files make sure you update the mkdocs.yml file. https://github.com/shouldly/shouldly/tree/master/docs
Top level is a single markdown file, second level indicates a H2 (or ##) in that file
All these should show the case sensitivity options.
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.
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
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!