Skip to content
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

Link to full Mink API results in a 404 #22

Open
Relequestual opened this issue Sep 23, 2014 · 29 comments
Open

Link to full Mink API results in a 404 #22

Relequestual opened this issue Sep 23, 2014 · 29 comments

Comments

@Relequestual
Copy link

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
Copy link
Member

stof commented Sep 25, 2014

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
Copy link
Author

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
Copy link
Member

stof commented Sep 29, 2014

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
Copy link
Author

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
Copy link
Author

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

@stof
Copy link
Member

stof commented Sep 29, 2014

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
Copy link

Fusty commented Sep 29, 2014

Excellent, I'd love to contribute as well

@Relequestual
Copy link
Author

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
Copy link
Member

stof commented Sep 29, 2014

@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
Copy link
Author

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
Copy link
Member

stof commented Sep 30, 2014

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

@wouterj
Copy link
Contributor

wouterj commented Oct 1, 2014

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
Copy link

@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
Copy link
Author

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

@sobi3ch
Copy link

sobi3ch commented Dec 16, 2014

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
Copy link
Member

stof commented Jan 7, 2015

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
Copy link
Member

aik099 commented Jan 7, 2015

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:

@stof
Copy link
Member

stof commented Jan 7, 2015

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
Copy link
Contributor

wouterj commented Jan 7, 2015

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

@stof
Copy link
Member

stof commented Jan 11, 2015

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

@aik099
Copy link
Member

aik099 commented Jan 11, 2015

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
Copy link
Member

stof commented Jan 12, 2015

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
Copy link
Member

aik099 commented Jan 12, 2015

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

@sobi3ch
Copy link

sobi3ch commented Jan 16, 2015

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

@aik099
Copy link
Member

aik099 commented Jan 16, 2015

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

@aik099
Copy link
Member

aik099 commented Jan 16, 2015

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
Copy link
Member

stof commented Jan 16, 2015

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

@sobi3ch
Copy link

sobi3ch commented Jan 16, 2015

Nice one!

@williamdes
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

8 participants