Ce répertoire est archivé au profit de https://github.com/etalab/admin_api_entreprise/
Il reste cependant en production jusqu'à fin 2023 ici : https://v2.entreprise.api.gouv.fr/
You can view the sandbox branch at this url: https://api-entreprise-sandbox.netlify.app/
bundle exec jekyll serve
npx netlify-cms-proxy-server
localhost:4000/entreprise.api.gouv.fr/catalogue
localhost:4000/entreprise.api.gouv.fr/admin
The PDF is generated by mina with Pandoc (+texlive, +xelatex) with a command like this:
pandoc cgu.md -o cgu.pdf --latex-engine=xelatex
A rake task is available :
bundle exec rake cgu_to_pdf
So it need to have installed:
This command deploy master
by default, you probably should merge gh-pages
into master
bundle exec mina deploy to=[sandbox|production] domain=[sandbox|production]
If you want to deploy on all domains:
bundle exec rake deploy
For production1.entreprise.api.gouv.fr
domain=production1.entreprise.api.gouv.fr
bundle exex mina setup domain=$domain to=production
bundle exex mina deploy domain=$domain to=production
You can index locally with the following command line:
bundle exec ruby ./bin/algolia_indexer.rb
You have to set the admin API key in _algolia_api_key
It only handles support for now.
Le site vitrine d'API Entreprise est disponible à l'adresse https://entreprise.api.gouv.fr.
Il s'agit d'un site statique en Jekyll dont les sources sont hostées sur Github.
Vous pouvez désactiver / activer une notification en haut de page.
Plus d'infos dans le fichier _data/notification.yml
Vous pouvez désactiver / activer l'affichage d'une modal sur le site de manière globale.
Plus d'infos dans le fichier _data/popup.yml
La page de support permet de centraliser l'intégralité des questions les plus fréquemment posées, et dans le cas où la réponse à la question de l'utilisateur n'y est pas, on précise l'adresse email pour nous écrire.
L'objectif est de réduire au maximum le support qu'on reçoit sur les requêtes
récurrentes des utilisateurs : toutes les références au support doivent pointer
sur cette page (ie /support/
).
En production, le site est servi à la racine du domaine entreprise.api.gouv.fr.
En sandbox, sur Github Pages (plus d'information sur l'utilisation de Github Pages ci-dessous), le site est servi à l'adresse https://etalab.github.io/entreprise.api.gouv.fr/. La branche source pour Github Pages est gh-pages.
Pour que le site soit fonctionnel dans les deux environnements il est nécessaire que la résolution des URLs soit indépendante de la présence
ou non d'un préfixe d'URL. Pour cela, l'option baseurl
dans le fichier \_config.yml
, qui permet de spécifier un préfixe d'URL,
est évaluée à "/entreprise.api.gouv.fr" pour que le site fonctionne sur Github Pages. Pour que le site soit servi directement à la racine du
domaine, le site est build avec l'option --baseurl ''
fournie à la ligne de commande et qui efface le préfixe d'URL.
Il est indispensable que des profils non techniques puissent éditer du contenu sur le site statique d'API Entreprise, cela est même rédhibitoire quant au choix de la solution. Le site vitrine historiquement fait en Jekyll répond au besoin à deux pré-requis près :
Le gros avantage de Github ici c'est Github Pages car nous n'avons pas d'intégration continue en place à ce jour.
Github Pages affichera automatiquement le résultat des changements appliqués poussés sur la branche gh-pages
.
Une version à jour de cette branche sera donc disponible à la visualisation à l'adresse https://etalab.github.io/entreprise.api.gouv.fr/.
Qu'est-ce que cela veut dire concrètement pour les équipes fonctionnelles ?
gh-pages
.
Cela évite une sursoliciation des équipes techniques, favorise l'indépendance des équipes métier et surtout il n'y a aucun risque :
Si tout est cassé, ce n'est pas grave car ce n'est pas en production, et grâce à Github Pages, vous pouvez être presque entièrement autonomes pour "réparer".master
viennent de gh-pages
. Pourquoi ? Déjà parce que vous avez vu ce que cela donne en sandbox,
vérifiez que ça ne cassait rien, et validez entre vous que c'était prêt pour la prod. Ensuite, pour l'équipe technique,
cela permet de simplement aller voir en sandbox (et c'est bien plus agréable que via le diff dans github) avant de déployer.Le templating du site Jekyll est en place pour que l'ajout d'élément de contenu au site web soit simple : uniquement en Markdown et avec le minimum de configuration.
La procédure d'ajout de contenu est détaillée ci-après. Aujourd'hui, il est possible d'éditer trois types d'éléments :
Exemple de rendu pour le contenu suivant :
---
layout: article
title: Mon super titre !
---
## Je veux parler de ça
### Premier sous titre
Wow sympa, tu sais que tu peux aussi écrire en **gras**.
### Deuxième sous titre
En _italique_ ça marche aussi, il y a aussi pleins de trucs et astuces :
1. truc 1
2. astuce 2
- en fait une liste sans ordre c'est bien aussi
- non ?
On peut même ajouter des [liens](https://www.markdownguide.org/cheat-sheet/) vers la documentation de la syntaxe de Markdown !
Plus de détails au cas par cas ci-dessous !
Une liste des cas d'usage est disponible à la page "Cas d'usage" accessible depuis l'en-tête du site ou à l'url /cas_usage/
. Cette page ne fait que
lister les cas d'usage documentés, chaque élément de la liste n'étant qu'un lien hypertexte vers la page de description du cas d'usage en question.
Pour ajouter un cas d'usage il suffit de créer un nouveau fichier avec dans le dossier \_use_cases
, par exemple \_use_cases/marches_publics.md
. Le nom du fichier n'a
aucune incidence sur le rendu mais il est préférable de rester cohérent pour identifier facilement les différents éléments, par contre il est
important que l'extension soit bien en Markdown .md
.
Pour un cas d'usage, les éléments de configuration suivant sont nécessaires. Il doivent être placée tout en haut du fichier, en en-tête :
---
layout: article
title: Mon cas d'usage
---
Les fournisseurs de données partenaires d'API Entreprise sont listés à la page "Données disponibles", à l'adresse /donnees_disponibles/
.
Cette page référence la liste de tous les fournisseurs de données qui ont une page d'information dans les sources.
Cette page est aussi le point d'entré pour les données : pour chaque fournisseur sont listées les liens vers les pages de documentation des
données mises à disposition. Plus sur l'édition du contenu des données ci-dessous
Pour ajouter un fournisseurs de données il suffit de créer un nouveau fichier avec dans le dossier \_providers
, par exemple \_providers/ademe.md
.
Le nom du fichier n'a aucune incidence sur le rendu mais il est préférable de rester cohérent pour identifier facilement les différents éléments,
par contre il est important que l'extension soit bien en Markdown .md
.
Pour ajouter un logo à côté du texte à côté du texte descriptif du fournisseur, il faut télécharger l'image et la placer dans le dossier assets/images/providers/
à côté de celles déjà présentes.
Pour un fournisseur de données, les éléments de configuration suivant sont nécessaires. Il doivent être placée tout en haut du fichier, en en-tête :
---
title: Mon fournisseur
label: fournisseur
logo: "/assets/images/providers/logo.png"
sources_url: https://www.fournisseur.fr/lien/vers/une/éventuelle/documentation/fournisseur
---
Les données disponibles sont listées, par fournisseurs, à la page "Données disponibles" (adresse /donnees_disponibles/
.
Cette liste n'est constituée que de liens hypertextes vers les pages de description des données.
Pour ajouter une description d'une donnée il suffit de créer un nouveau fichier avec dans le dossier \_available_data
, par exemple \_available_data/ma_donnee.md
. Le
nom du fichier n'a aucune incidence sur le rendu mais il est préférable de rester cohérent pour identifier facilement les différents éléments,
par contre il est important que l'extension soit bien en Markdown .md
.
Pour une description de données, les éléments de configuration suivant sont nécessaires. Il doivent être placée tout en haut du fichier, en en-tête :
---
layout: article
title: Certificat RGE
provider_label: ademe
---
⚠️ En environnement de développement, les modifications peuvent ne pas être visible car par défaut, le contenu affiché provient du cache d'Algolia.
Les pages ayant une barre de recherche et du contenu dynamique utilisent Algolia, ce qui implique que le contenu affiché est directement extrait d'Algolia.
Ce que cela implique : les modifications effectuées en locale n'apparaissent pas
directement car il faut à chaque fois réindexer le contenu sur Algolia à l'aide
d'un script (./bin/algolia_indexer.rb
). Cette tâche est effectuée lors des
déploiements, et étant donné que l'on est limité en nombre d'opérations, on ne
peut pas se permettre de le faire à chaque modification.
Afin de pouvoir vérifier le contenu ajouté sans réindexer le contenu sur Algolia,
il est possible de désactiver la recherche en ajoutant à l'URL ?disable-search=1
ou en désactivant le javascript (ce qui permet aussi de rendre la page utilisable en
cas de javascript désactivé #accessibilité).
Exemple : http://127.0.0.1:4000/entreprise.api.gouv.fr/doc/?disable-search=1
Il est possible, afin d'affiner les résultats de recherche, de configurer des synonymes.
Ceci se passe dans le fichier _config.yml, sous la clé
algolia->synonyms
.
La documentation générale se trouve ici: Synonym La documentation technique: Save Synonym