New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate docs to readthedocs.org #308

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

Comments

Projects
None yet
6 participants
@JakeGinnivan
Member

JakeGinnivan commented Sep 29, 2015

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

This comment has been minimized.

Show comment
Hide comment
@JosephWoodward

JosephWoodward Sep 29, 2015

Member

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

Member

JosephWoodward commented Sep 29, 2015

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

@phil-scott-78

This comment has been minimized.

Show comment
Hide comment
@phil-scott-78

phil-scott-78 Sep 30, 2015

Contributor

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.

Contributor

phil-scott-78 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

This comment has been minimized.

Show comment
Hide comment
@JakeGinnivan

JakeGinnivan Oct 1, 2015

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.

Member

JakeGinnivan commented Oct 1, 2015

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.

@phil-scott-78

This comment has been minimized.

Show comment
Hide comment
@phil-scott-78

phil-scott-78 Oct 1, 2015

Contributor

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.

Contributor

phil-scott-78 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

This comment has been minimized.

Show comment
Hide comment
@billglover

billglover Oct 13, 2015

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.

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

This comment has been minimized.

Show comment
Hide comment
@JakeGinnivan

JakeGinnivan Oct 13, 2015

Member

@billglover merged now :) sorry about that

Member

JakeGinnivan commented Oct 13, 2015

@billglover merged now :) sorry about that

@JakeGinnivan

This comment has been minimized.

Show comment
Hide comment
@JakeGinnivan

JakeGinnivan Jan 1, 2016

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

Member

JakeGinnivan commented Jan 1, 2016

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

This comment has been minimized.

Show comment
Hide comment
@JosephWoodward

JosephWoodward Jan 4, 2016

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?

Member

JosephWoodward commented Jan 4, 2016

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

This comment has been minimized.

Show comment
Hide comment
@JakeGinnivan

JakeGinnivan Jan 4, 2016

Member

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

Member

JakeGinnivan commented Jan 4, 2016

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

@JosephWoodward

This comment has been minimized.

Show comment
Hide comment
@JosephWoodward

JosephWoodward Jan 4, 2016

Member

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

Member

JosephWoodward commented Jan 4, 2016

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

@JosephWoodward

This comment has been minimized.

Show comment
Hide comment
@JosephWoodward

JosephWoodward Jan 6, 2016

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

Member

JosephWoodward commented Jan 6, 2016

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

This comment has been minimized.

Show comment
Hide comment
@mwhitis

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

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

This comment has been minimized.

Show comment
Hide comment
@JosephWoodward

JosephWoodward Jan 12, 2017

Member

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

Member

JosephWoodward commented Jan 12, 2017

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

@morrme

This comment has been minimized.

Show comment
Hide comment
@morrme

morrme Mar 26, 2017

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?

morrme commented Mar 26, 2017

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?

@JosephWoodward

This comment has been minimized.

Show comment
Hide comment
@JosephWoodward

JosephWoodward Apr 6, 2017

Member

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

Member

JosephWoodward commented Apr 6, 2017

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

@morrme

This comment has been minimized.

Show comment
Hide comment
@morrme

morrme Apr 21, 2017

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

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

morrme commented Apr 21, 2017

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

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

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