Massive Documentation Improvements #280
Conversation
|
see #90 |
|
This would be a good intermediate point though. |
|
Firstly, thanks this is awesome. We have intentions of moving the docs to RST and putting them on read the docs, splitting the readme would have been the first step. Only thing that caught my eye was the numbering of the the files, is that some sort of convention I don't know about? It just seems strange to me, if I wanted to re-order the TOC or indeed, insert something part way through, I'd either have to re-number of start messing about with 21a etc. |
|
I prefixed them with numbers so they appeared in the intended reading order in the folder, instead of being ordered alphabetically. I can get rid of the numbers if you like? |
|
Yeah I see, there are quite a few to have randomly in one dir without a proper way to view them etc. 👍 from me, I'll give @padraic a short chance to shout about something and then merge, thanks again. |
|
Sounds great. :) |
|
|
||
| This will install the required PHPUnit and Hamcrest dev dependencies and create the | ||
| autoload files required by the unit tests. Navigate to the "tests" directory and run the | ||
| `vendor/bin/phpunit` command to run the unit tests. With a wee bit of luck, there will be |
There was a problem hiding this comment.
you don't need to navigate to the tests directory, since this project has a correctly configured phpunit config file.
There was a problem hiding this comment.
I'm not a native, but "a wee bit of luck" sounds strange, what is "wee"?
There was a problem hiding this comment.
I didn't write this. I just moved it from the readme and made a few small changes. "wee" is Scottish for "a little".
There was a problem hiding this comment.
I'll update this to be correct, and I'll change the "wee" to something more globally understandable. lol
|
Do the contributing docs look better now @wouterj? |
| @@ -0,0 +1,53 @@ | |||
| Installation | |||
| ------------ | |||
There was a problem hiding this comment.
markdown can better work with headings indicated by # (level 1), ## (level 2), etc. characters
There was a problem hiding this comment.
This is how @padraic had it. No need to change it. It's valid markdown.
There was a problem hiding this comment.
I've changed this in 58044eb.
|
@GrahamCampbell before going further, do you want me to review the hole doc in this PR or should I create another PR instead after this is merged? |
|
You can make comments here for me if you like, or you can submit a pull request to my docs branch. Then I can merge them into my branch. Then my docs branch with your changes can go into the main repo. |
|
Give me a min before you go wild though. I am making a few changes first... |
|
I'll go for your second suggestion, I'll make a PR to your branch. That the most efficient method :) Expect something tomorrow morning 😉 |
|
Squashed and pushed. There were way too many little commits before. Now it's all tidy and ready to go. |
|
@davedevelopment and @padraic, how does this look now? |
|
One last question, why did you choose to use uppercase file names? I prefer to use lowercase file names instead |
|
Coz I can. |
|
I'm not worried about case for file names, the plan is to migrate them to padraic/mockery-docs anyway, we can deal with that then. For now, this is a lot better, thanks to both of you for your efforts. P.S. @wouterj we've never met, but @weaverryan speaks very highly of you, glad to have you helping out :) |
|
Is this good to merge then @davedevelopment? |
[READY] Massive Documentation Improvements
|
@GrahamCampbell done |
|
Awesome! |
|
@GrahamCampbell I truly appreciate this :). The gigantic mega-README has finally been tamed :P. May need links back to contents page at top/bottom of each page for those who get a bit lost. |
|
Sure, I can add links... |
|
How would this sort of thing look? http://i.imgur.com/A5Lpbfu.png |
|
Just something that occurred to me, we could use viewdocs.io for the time being, it basically renders markdown in a project's docs dir. |
|
See #287. |
|
@davedevelopment the hardest part is now already done by @GrahamCampbell converting to Sphinx and moving it to the docs repo isn't that hard. If @GrahamCampbell promises to be patient (otherwise we get lots of merge conflicts) I can work on transforming it the comming 2 days. Using viewdocs.io first and then readthedocs.org will just be confusing for people reading (and linking to) the docs. |
|
@wouterj righto, I'll leave you two to it :) |
|
That's the last commit I was going to make for now to the docs. It'd be good if it could go in. |
|
ok, thanks @GrahamCampbell. If you want to help me, you can always ping me :) |
|
I am pretty busy this week, but if you push your changes so I can see them onto a branch on your fork, I'll see what I can do. You can contact me directly at graham@mineuk.com if you need me. :) |
|
The party will continue over at padraic/mockery-docs#1. |
I've corrected a few typos and formatting derps, and I have moved all the documentation to a docs folder. Each h2 heading now has it's own file. I have updated the contents page on the readme for this change.