Website documentation is out of date

[atymic]

The website is still showing the documentation for the 3.x major version, as well as a very outdated provider list.

http://geocoder-php.org/Geocoder/

I think we should either update the site (and have it automatically be re-built/deployed using CI on merge to master) or direct users to the github repo.

I'll to look into it and create a PR when I have a chance.

[atymic]

This could be a good opportunity to give the website a bit of an update :)

[jbelien]

Yes, I got confused by the (old) website as well when I started to use this library ^^ I guess that a simple redirection to the repo would be enough!

@willdurand I guess you're the owner of the domain name ?

[atymic]

I'd be happy to have a crack at updating the website :) I think it should be pretty easy to pull in the content from the main repo and build something automatically

I still think having a website is a good thing, rather than just 301'ing it to GH.

[atymic]

@jbelien @Nyholm

Have a gander at this: https://nostalgic-jang-a7bbf3.netlify.com/

It's a static site built using jigsaw that automatically pulls in the geocoder docs (so it can run in CI) 😄

Code here: https://github.com/atymic/geocoder-site

[atymic]

We can also integrate algolia docsearch one we are up and running for awesome docs search!

[Nyholm]

Wow. That looks great. How do you fetch the data?

Could we move our readme to /docs and only promote the website?

[jbelien]

Damn it looks good ! 😍

Could we move our readme to /docs and only promote the website?

Seems like a good plan 👌

[atymic]

Wow. That looks great. How do you fetch the data?

As it's using jigsaw, I just added a listener that runs before it's built. It's pretty simple, it just clones the repo and extracts the appropriate .md files:

https://github.com/atymic/geocoder-site/blob/master/extend/DocumentationImporter.php

[atymic]

@Nyholm @jbelien

How would you like to proceed with this? I assume you will create the netlify account & github repo?

[Nyholm]

@willdurand We are planning to update the website, are you owner of geocoder-php.org?

@atymic: Could we use this repo: https://github.com/geocoder-php/geocoder-php.github.io?

[atymic]

@atymic: Could we use this repo: geocoder-php/geocoder-php.github.io?

We could actually deploy direct to there and update the existing website. I can create a PR if you would like?

We are planning to update the website, are you owner of geocoder-php.org?

Would be good to update it anyway hopefully, it needs HTTPs and such :)

[willdurand]

@willdurand We are planning to update the website, are you owner of geocoder-php.org?

yep, I am.

[atymic]

I will make a PR against that repo today :)

[atymic]

Oh, the problem with that is building the site once the docs changes. GH pages doesn't support any way of triggering builds without a commit to that branch, where as with netlify we can use a webhook to trigger the site to update on merge to master on the main repo.

It also has CI so the site is built automatically, no need to set up travis and such.

Only config required is this: https://github.com/atymic/geocoder-site/blob/master/netlify.toml

If we were going to use netfliy, maybe would make sense to put it in a different repo, not one with github pages in the name? (maybe archive the old one).

If you would prefer to use GH pages, however have a go at getting the CI set up when I have a chance.

[jbelien]

@atymic The new GitHub Actions (https://github.com/features/actions) could probably help with the build :)

[Nyholm]

I dont mind using netify. It looks simple as you already set it up.

I think we should use the same repo, disable github pages and then ask William to update the DSN settings.

What do you think?

[jbelien]

I think we should use the same repo, disable github pages and then ask William to update the DSN settings.

I think it's the easiest indeed 👍

[willdurand]

How can we guarantee that we keep ownership on Netify in the future? Say, @atymic disappears, how can we update Netify?

[jbelien]

How can we guarantee that we keep ownership on Netify in the future? Say, @atymic disappears, how can we update Netify?

Maybe it's best that you own/run the Netflify instance (it's free). The (new) website repo should also contain an INSTALL file with the whole process to run it (included on Netlify).

Then you can run and configure it (see https://www.netlify.com/docs/custom-domains/)

[atymic]

How can we guarantee that we keep ownership on Netify in the future? Say, @atymic disappears, how can we update Netify?

I would suggest that you own the account, all you need to do is create it, hook it up to the domain and point it at the repo. Everything else can be configured or updated in the netlify.toml :)

[atymic]

I think we should use the same repo, disable github pages and then ask William to update the DSN settings.

Only though with using that repo is that it has .github.io from github pages in the name, and renaming repos on GH tends to break everything.

[Nyholm]

Why would you rename the repo?

[atymic]

Why would you rename the repo?

Fair enough, haha. Just my OCD kicking in 😝 with it being named like GH pages but using netlify.

I will create a PR today to that repo, and if @willdurand adds netlify to it (without the custom domain right now) it can start building PR/branch previews

[willdurand]

I am not sure to understand why we need Netlify.

• Aren't gh-pages enough to host the website?
• What kind of automation do we need to update a website that has its files versioned in the .github.io repo?

[atymic]

Aren't gh-pages enough to host the website?

Yes, github pages will work.

What kind of automation do we need to update a website that has its files versioned in the .github.io repo?

The issue is we need a way to trigger builds of the website when the main repo is updated. AFAIK GH pages doesn't have a way of doing this without a commit to the repo.

We could probably configure travis somehow on the main repo to make a commit to the website repo to trigger a build.

[willdurand]

Which main repo? The docs live in the .github.io repo, not in the main repo. Does your new (very pretty) website extract information from geocoder-php/Geocoder?

[atymic]

Does your new (very pretty) website extract information from geocoder-php/Geocoder?

Yes, it does: https://github.com/atymic/geocoder-site/blob/master/extend/DocumentationImporter.php

[atymic]

I think that having the docs automatically updated when the main repo is updated is a good idea, as it means that they will be consistent. Currently, you could get confused by the web site as it's out of date, and while we can manually update it it, it will be out of date with the next package/documentation updates.

[willdurand]

Ahhhh! I get it now, very cool! So I guess it makes sense to use Netlify unless we can setup GitHub Actions and assuming it's easier than Netlify.

[atymic]

Ahhhh! I get it now, very cool! So I guess it makes sense to use Netlify unless we can setup GitHub Actions and assuming it's easier than Netlify.

Netlify actually has built in CI/CD, so there's no need for github actions. https://www.netlify.com/docs/continuous-deployment/

All we need is a webhook setup in the settings of the main repo, which will trigger a build & deploy of the site on merge https://www.netlify.com/docs/webhooks/#incoming-webhooks

[willdurand]

Alrighty, so I created a Netlify site bound to the .github.io repo: https://geocoder-php.netlify.com/ (currently deploying).

Then, I need to setup a webhook on Geocoder, right?

[jbelien]

Netlify actually has built in CI/CD, so there's no need for github actions.

I guess @willdurand (and myself) mentioned GitHub Actions to host everything using GitHub Pages.

Never used GitHub Actions so I would go for Netlify too but it was in case we want to have everything here on GitHub 😋

[atymic]

Alrighty, so I created a Netlify site bound to the .github.io repo: geocoder-php.netlify.com (currently deploying).

Sweet :)

Then, I need to setup a webhook on Geocoder, right?

Yep, you can follow this guide: https://developer.github.com/webhooks/creating/

Just point it to the build webhook created in netlify.

PR incoming to the site repo.

[willdurand]

I guess we're good?

[atymic]

Yep, looks good, thanks!

Netlify will automatically build a preview site for the PR as well :) https://github.com/geocoder-php/geocoder-php.github.io/pull/10 https://deploy-preview-10--geocoder-php.netlify.com/

[Nyholm]

@atymic, I've given you write access to https://github.com/geocoder-php/geocoder-php.github.io

Should we move the docs in geocoder-php/Geocoder to a /docs subfolder and keep the Readme.md short with just a quick code example and link to the website? Is it smart to do this now or should we wait?

[willdurand]

I think the whole point of Netlify was to keep the docs in .github.io. @atymic's patch has a script to pull and parse Geocoder.

[atymic]

@atymic, I've given you write access to geocoder-php/geocoder-php.github.io

Thanks, the PR is here: https://github.com/geocoder-php/geocoder-php.github.io/pull/11

Should we move the docs in geocoder-php/Geocoder to a /docs subfolder and keep the Readme.md short with just a quick code example and link to the website? Is it smart to do this now or should we wait?

I think we should wait until the new site is live :)

I think the whole point of Netlify was to keep the docs in .github.io. @atymic's patch has a script to pull and parse Geocoder.

I think @Nyholm is suggesting moving them to a subfolder in this repo, and linking to the website in the root package readme, the github.io repo would still just contain the website code (and still update from this repo)

[atymic]

@willdurand

When you are free could you update the domain to point to netlify please? The PR was merged into the site repo.

Thanks 😄

[willdurand]

When you are free could you update the domain to point to netlify please?

done.

I think @Nyholm is suggesting moving them to a subfolder in this repo, and linking to the website in the root package readme, the github.io repo would still just contain the website code (and still update from this repo)

Not sure I understand. What should be moved to the main repo?

[jbelien]

⚠️ We need to replace http://geocoder-php.org/Geocoder by http://geocoder-php.org/ here on the main GitHub repo !

---

@atymic The http://geocoder-php.org/branding doesn't work!

[atymic]

⚠️ We need to replace http://geocoder-php.org/Geocoder by http://geocoder-php.org here on the main GitHub repo !

I'll create a PR for that, also a redirect rule in case anyone had the old page bookmarked

The http://geocoder-php.org/branding doesn't work!

Good catch will get that fixed.

[atymic]

I've fixed the broken link with a PR in the site repo to redirect it to the home page, however when you have a chance @willdurand could you update it?

https://github.com/geocoder-php/geocoder-php.github.io/pull/14

[willdurand]

done. Thanks for the redirects, it's important to not break existing URLs.

[atymic]

I'll close this PR now the new site is live 😃 Feel free to create issues in that repo if there are problems: https://github.com/geocoder-php/geocoder-php.github.io/