Migrate docs to readthedocs.org #308

Open
JakeGinnivan opened this Issue Sep 29, 2015 · 13 comments

Projects

None yet

5 participants

@JakeGinnivan
Member

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

Equality

  • ShouldBe
    • Object
    • Numeric
    • DateTime(Offset)
    • TimeSpan
    • String (should link to string ShouldBe section)
    • Enumerable (link to ShouldBe in enumerable section)
  • ShouldNotBe
    • Object
    • Numeric
    • DateTime(Offset)
    • TimeSpan
  • ShouldBeTrue/False
  • ShouldBeNull
    • ShouldNotBeNull
  • ShouldBeSameAs
    • ShouldNotBeSameAs
  • ShouldBeOneOf
    • ShouldNotBeOneOf
  • ShouldBeGreater/LessThan
    • ShouldBeGreaterThan
    • ShouldBeLessThan
    • ShouldBeGreaterThanOrEqualTo
    • ShouldBeLessThanOrEqualTo
  • ShouldBeInRange
    • ShouldNotBeInRange
  • ShouldBeOfType
    • ShouldNotBeOfType
  • ShouldBeAssignableTo
    • ShouldNotBeAssignableTo

Strings

All these should show the case sensitivity options.

  • ShouldBe
    • ShouldNotBe
  • ShouldStartWith
    • ShouldNotStartWith
  • ShouldEndWith
    • ShouldNotEndWith
  • ShouldMatch
    • ShouldNotMatch - Overload missing see #312
  • ShouldBeNullOrEmpty
    • ShouldNotBeNullOrEmpty
  • ShouldBeNullOrWhiteSpace
    • ShouldNotBeNullOrWhiteSpace
  • ShouldContain
    • ShouldNotContain
  • ShouldContainWithoutWhitespace
    • ShouldNotContainWithoutWhitespace

Enumerable

  • ShouldBe (move from equality section)
  • ShouldAllBe
  • ShouldBeEmpty
    • ShouldNotBeEmpty
  • ShouldBeSubsetOf
  • ShouldBeUnique
  • ShouldContain
    • T
    • Predicate<T>
  • ShouldNotContain
    • T
    • Predicate<T>

Dictionaries

  • ShouldContainKey
    • ShouldNotContainKey
  • ShouldContainKeyAndValue
    • ShouldNotContainValueForKey

Exceptions

  • Should.Throw
    • Action<T>
    • Func<T>
    • Task
    • ShouldThrow extension method
    • ShouldThrowAsync
  • ShouldNotThrow
    • Action<T>
    • Func<T>
    • Task
    • ShouldThrow extension method

Other

  • ShouldCompleteIn
  • ShouldSatisfyAllConditions
  • DynamicShould
    • HaveProperty
@JosephWoodward
Member

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

@enkafan
Contributor
enkafan commented Sep 30, 2015

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.

@JakeGinnivan
Member

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.

@enkafan
Contributor
enkafan commented Oct 1, 2015

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.

@billglover

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.

@JakeGinnivan
Member

@billglover merged now :) sorry about that

@JakeGinnivan
Member

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 :)

@JosephWoodward
Member

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?

@JakeGinnivan
Member

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

@JosephWoodward
Member

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

@JosephWoodward
Member

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!)

@mwhitis
mwhitis commented Jan 12, 2017

@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.

@JosephWoodward
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment