Link to full Mink API results in a 404

[Relequestual]

I'd like to see the full docs for Mink, specifically the API, but the link results in a 404. I've googled for Mink API, but I'm unable to find a list of all the functions. Any idea where I can find it?

[stof]

hmm, given the Mink doc is not rendered online anymore for now, the generated API doc is not available anymore currently. So to see the available methods, you would need to look at the code. any IDE should be able to show you the methods available in a class. And you can also run phpdocumentor on the Mink codebase locally if you really want to have a generated API doc instead.

[Relequestual]

OK. Sure, I can look at the code, but surely it's easier for most people to have some online resource for this? What was the decision process behind not having the Mink doc rendered anymore?

Partly ralaetd: What is actually happening with Mink now? Previously it had it's own site and now that just redirects to a single page markdown file on github. I'm starting to feel like choosing Mink may have been a mistake =/

[stof]

Well, this is because behat.org is not rendered anymore currently, and so the subdomain showing the Mink doc was killed at the same time.
My plan is to improve this documentation about Mink and converting it to rST to use ReadTheDocs to handle the rendering. This way, we will not depend on pinging Konstantin to update the doc website when changing it (which was the case before it was dropped entirely). but writing good doc takes time.

Note that the previous website was just this markdown file converted to HTML (which is done by Github as well) and the auto-generated API doc.

[Relequestual]

I understand. I know good docs take time. It's pretty furstrating trying to explain stuff to other people when I can't find the docs myself.

I guess this would be more a critique of the behat docs, but so many pages, when trying to view v3 from the 2.5 pages, page does not exist.

I should make pull requests, right? =/

[Relequestual]

Seriously, what can I do to help (if anything?)

[stof]

Well, give me until this evening, so that I can setup ReadTheDocs to render the Mink docs (I don't even need to convert Markdown to rST as this is already usign rST). Then, you will be able to start sending PRs to improve the Mink documentation.

To be honest, I'm not sure rendering the generated API doc is that useful. A generated API doc is not the best way to document a library at all. The doc should explains what you can do with Mink and how to use it. but giving the list of all methods of a class is something that all IDEs are doing already at the time of the writing.
So I don't think I will render the API doc yet (unless there is a free hosted tool allowing to do it automatically without having to setup our own server building it each time, in which case I might reconsider this option)

[Fusty]

Excellent, I'd love to contribute as well

[Relequestual]

Lack of web based docs is a stumbling block for new users who still feel feel they are not quite confident using the CLI, especially those on windows machines (where the cli is just horrible). I saw a behat / mink demo quite a number of years ago. Only just starting to use it now.

[stof]

@Relequestual the question is whether the generated API doc is really what you need to get started. My guess is that the answer is "no"

[Relequestual]

Well, it would be a start. Without the cheatsheet that's out there, I'd have very little idea what I can actually do within my own Context classes when I extend RawMinkContext. There's a small amount on Step Execution Chaining in the 2.5 docs, but I understand that's more "meta steps" and discouridged in favour of extending RawMinkContext, and writing your own definitions using that. I actually had to ask around to work out that's how I'm supposed to do it! =/

Unrelated: How do I go about getting ST3 to show me methods from RawMinkContext or MinkSession?

[stof]

I don't know ST3, so I cannot help you configuring autocompletion in it. Ask the ST community instead

[wouterj]

API doc is implementation documentation. You are looking for usage documentation, you won't get that with the API doc.

Mink and MinkExtension as good docs on how to install/confiure Mink (and Mink with Behat). The steps can be found using bin/behat -dl and by looking at the RawMinkContext class. Of course, good docs will make it easier, but there is not much wrong with looking at RawMinkContext and the definition list of Behat.

[minrwhite]

@Relequestual As a workaround, you can use Wayback Machine to look at the API docs as they were:

http://web.archive.org/web/20140701093815/http://mink.behat.org/api/

[Relequestual]

Thanks! I managed to find another posting of it which looked a bit nicer =]

[sobi3ch]

I'm working on Linux as web developer from almost 10 years and CLI is my best friend, but I need to say @Relequestual has 100% sure in his arguments. I think this is standard in those days that you can go to project page and read nice formatted docs WITH api as well. And message like

@Relequestual the question is whether the generated API doc is really what you need to get started. My guess is that the answer is "no"

..sounds like private opinion.

I'm using ton of different tools and wasting my time on firing IDE to see mink API look for mi cumbersome, "eating" my time to figure out basic information.

To just give basic example why jQuery, Drupal, Symfony, Django, AngularJS and other have their API's?

I think Behat with Mink are realy great tools and they should have proper API docs. If no then at least there shouldn't be issues like this one. :)

[stof]

OK, the doc is now finally rendered online again thanks to ReadTheDocs (the domain mink.behat.org is not yet pointing to it, but this will be done soon). It still needs a big rewrite.

Regarding the API doc, is there a (free) tool allowing to generate it automatically for a github repo, like ReadTheDocs does for our rST documentation ? If yes, it should be easy to make it available online again. Otherwise, it is more painful.

[aik099]

There is a tool called Sami (https://github.com/FriendsOfPHP/Sami), but it's not automatic. This tool is used to generate Symfony API documentation as well.

I recommend:

1. creating separate repo for API
2. creating a script that will take current Mink (and maybe driver) code and generate docs from them
3. that script will produce html/js/css files and we manually need to add them to git

Examples:

• https://github.com/qa-tools/api/tree/gh-pages - see the generate.sh script and sami_config.php for Sami configuration
• http://api.qa-tools.io/master/index.html
• http://api.symfony.com/2.6/index.html

[stof]

I know about Sami and phpdocumentor. But this requires doing the work manually.

Using github pages for that is an option, but it will not allow to automate building this each time the code is updated. This is why I'm wondering whether there is a tool building on top of these to provide hosted API doc (like ReadTheDocs does for Sphinx doc). It would be great to have the API doc for the master branch too rather than only for releases.

There is another question here: how can we handle the drivers, which are in separate repos ? I'm sure that Sami does not provide a way to handle this (it would have to be a separated API doc for each driver) as Symfony does not have such use case. Maybe phpdocumentor supports something to make it better

[wouterj]

Travis allows to push to github, so you can generate them when doing builds on the master branch

[stof]

I just found http://apigenerator.org/ which might be what we need

[aik099]

Both phpDocumentor or ApiGen (only these ones are supported by that service) create pretty ugly and non-usable documentation compared to what Sami does IMO.

[stof]

I see 1 drawback in Sami though: its generated documentation relies on frames, making it a pain to share a link to the API documentation (and when you share a link, you don't get the complete UI: http://api.symfony.com/2.6/Symfony/Component/Routing/RequestContext.html)

[aik099]

Luckily this is no longer an issue with new 3.0 version (not released yet), where major theme rewrite was made using bootstrap.

[sobi3ch]

http://apigenerator.org/ looks good for me, in case there's no Sami 3.0 why not use it?

[aik099]

Considering that APIGen was used to create former Mink API documentation if I'm not mistaken.

[aik099]

But ApiGenerator isn't hosting platform. It says, that it generate docs on push and then adds a commit to your repo with the docs. We can do the same on Travis if we need to given that we grant appropriate right to it.

[stof]

Yeah, I'm planning to setup this on our end directly.

[sobi3ch]

Nice one!

[williamdes]

Sami had Doctum to replace it (https://github.com/code-lts/doctum#readme)