Dans le cadre de projets open-source, faire une documentation claire et lisible est un nécessité. Pour cela, ReadTheDocs permet de générer à partir de fichiers fournis au format Markdown une belle documentation.

Créer sa documentation avec Sphinx

Il faut tout d’abord installer le paquet

python-sphinx

$ sudo yum install python-sphinx

Après l’installation, allons dans le projet et créons le dossier de travail :

$ cd /chemin/de/votre/projet
$ mkdir docs
$ cd docs

On initialise le projet avec Sphinx :

$ sphinx-quickstart
Welcome to the Sphinx 1.1.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: 

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]: 

The project name will occur in several places in the built documentation.
> Project name: MyProject
> Author name(s): AuthorName

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 0.x.0
> Project release [0.x.0]: 

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]: 

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: 

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]: 

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]: 
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: 
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: 
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: 
> coverage: checks for documentation coverage (y/N) [n]: 
> pngmath: include math, rendered as PNG images (y/N) [n]: 
> mathjax: include math, rendered in the browser by MathJax (y/N) [n]: 
> ifconfig: conditional inclusion of content based on config values (y/N) [n]: 
> viewcode: include links to the source code of documented Python objects (y/N) [n]: 

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]: 
> Create Windows command file? (Y/n) [y]: n

Creating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Après avoir commité votre dossier

docs\\

Configurer son projet sur ReadTheDocs

Après avoir créé un compte, il faut aller sur le tableau de bord puis cliquer sur Import.

Je vais prendre PHPWord comme exemple pour lequel j’ai réalisé le début de la documentation.

La première partie du formulaire permet de définir le nom du projet, le dépôt et le type de dépôt du projet, suivi d’une description du projet.

La seconde partie du formulaire permet de définir la langue principale du projet, le type de documentation (que j’ai laissé par défaut), l’URL du projet, et l’URL de la documentation (soit http://xxxx.readthedocs.org soit http://xxxx.domain.tld, si vous pointez un sous-domaine vers ReadTheDocs). On clique ensuite sur “Create”.

Si on exécute actuellement un build manuellement, la documentation ne sera pas générée parce que ReadTheDocs ne sait pas où trouver la documentation dans le dépôt du projet. Pour cela, il faut aller dans les paramètres avancés (advanced settings) pour configurer le dossier où se trouve le fichier de configuration de la documentation. Dans notre exemple, c’est

docs/conf.py

Activer le webhook sur GitHub

Afin qu’à chaque commit, votre documentation soit regénéré automatiquement, il faut activer un webhook sur GitHub.
Pour cela, voici la procédure :

• Aller sur la page “Settings” de votre projet ;
• Aller sur l’onglet “Webhooks & Services” ;
• Cliquer sur le bouton “Configure services” ;
• Chercher “ReadTheDocs” dans la liste de services ;
• Cocher la case “Active” et Valider.

Voilà, la documentation Markdown de votre projet a désormais plusieurs avantages : historisée via Git, automatiquement générée via ReadTheDocs, simple avec le format Markdown. Maintenant, à vous de jouer.

Cet article Comment publier sa documentation via ReadTheDocs ? est apparu en premier sur RootsLabs.

Original post of Progi1984.Votez pour ce billet sur Planet Libre.

Nous y voila ! Dans la première partie de ce tutoriel, nous avons vu comment ajouter notre bouton au bon emplacement, avec le bon style qui convient. Mais pour le moment, ce bouton ne sert à rien, et il est donc temps de lui faire faire quelque chose !

Première chose à se demander : que veut-on exactement ? Car il est vrai que la réponse à cette question n’était peut-être pas très claire après la première partie. On va ici reproduire le même comportement que celui du bouton de WP Photo Sphere : lorsqu’il cliquera sur ce bouton, l’utilisateur verra apparaître la fenêtre d’ajout / édition des médias qu’il connaît déjà et, après validation de son choix, nous récupérerons des informations sur ce dernier, comme son ID par exemple.

Vous l’aurez compris : ici, tout se passe en JavaScript, donc commencez par créer un fichier JS. Avant toute chose, il nous faut inclure ce fichier dans la page d’administration de WordPress. Il faut savoir que ce dernier nous propose une fonction toute prête pour cela, permettant de lui dire que nous voulons qu’il inclue un script : l’avantage, c’est qu’il gère les dépendances et qu’il met tout au même endroit, pour plus de propreté :

wp_enqueue_script('mon-admin', 'mon-admin.js', array('jquery'), '1.0', true);
?>

Nous ne rentrerons pas ici dans les détails de cet appel de fonction, tout est dans la documentation et nous y reviendrons de toute façon dans un prochain tutoriel où nous verrons comment l’utiliser au mieux. Mais la question qui a sa place ici, c’est bien évidemment : où mettre cette fichue ligne ?

Dans une fonction, bien sûr, que vous créerez pour l’occasion :

function enregistrer_mon_script() {
	wp_enqueue_script('mon-admin', 'mon-admin.js', array('jquery'), '1.0', true);
}
?>

Reste à savoir quand appeler cette fonction. La réponse est encore et toujours la même : les actions. Plusieurs actions auraient pu nous aider ici, mais nous allons porter notre choix sur wp_enqueue_media qui est effectuée lorsque WordPress appelle tous les scripts nécessaires aux boutons de médias, ce qui fait donc de cette action la plus appropriée :

add_action('wp_enqueue_media', 'enregistrer_mon_script');
?>

Maintenant que notre script est appelé comme il faut, il faut encore lui mettre des trucs dedans, c’est toujours mieux. Nous utiliserons jQuery pour simplifier l’écriture de nos fonctions (d’où la dépendance demandée à WordPress). Cependant, si vous êtes anti-jQuery, rien ne vous empêche de faire sans, c’est plutôt simple.

Pour éviter tous les conflits, nous allons encapsuler tout notre code dans une fonction un peu spéciale :

jQuery(function($) {
	/* Tout notre code sera ici */
});

Cela permet d’utiliser le symbole $ en lieu et place de l’objet jQuery tout en évitant les conflits avec d’autres librairies utilisant ce symbole. À partir de maintenant, tout le code qui suit sera en réalité encapsulé dans cette fonction, que je ne réécrirai pas afin de ne pas alourdir inutilement cette page.

Commençons déjà par ajouter l’événement qu’il faut à notre bouton :

$(document).ready(function() {
		$('#mon-bouton').click(ouvrir_fenetre);
	});

D’où l’utilité d’avoir ajouté un id à notre bouton. Si vous ne l’avez pas fait, il n’est pas encore trop tard pour le faire et clamer haut et fort que si, en fait, c’était déjà fait.

Ces trois petites lignes sont assez explicites : lorsque tout le document est chargé, on indique que l’on veut exécuter la fonction ouvrir_fenetre() lorsque l’utilisateur clique sur notre bouton. C’est dans cette fonction que tout va se jouer.

Pour commencer, sachez que la fonction que l’on va construire ensemble n’est pas la façon de faire qu’utilise WordPress (vous trouverez un exemple dans le fichier /wp-admins/js/custom-background.js de votre installation WordPress). J’ai en effet choisi de faire un peu à ma sauce, mais c’est une question de préférence, rien ne vous empêche de faire autrement. Pour bien comprendre ce qu’on va faire ici, il faut que vous ayez en tête la manière dont on crée des variables statiques en JavaScript.

Nous allons donc créer notre fonction qui utilisera une variable statique stockant la fenêtre de médias. Nous pourrions en effet demander à WordPress de la recréer à chaque clic, mais comme ça consommerait des ressources inutilement, nous ne la créerons qu’une fois.

var ouvrir_fenetre = (function() {
		var fenetre = null;
 
		return function() {
				return false;
			};
	})();

Rien de bien mystérieux ici : on ne fait que créer notre fonction et initialiser notre variable statique à null. Notre fonction retourne false, ce qui peut peut-être vous intriguer, mais ça se comprend plutôt bien en fait : en faisant ceci, on indique au navigateur qu’il ne faut pas faire l’action du lien prévue par défaut (c’est-à-dire se rendre vers l’ancre vide # dans notre exemple).

Avant tout, la partie facile : une fois la fenêtre créée, il suffit pour l’ouvrir d’appeler la méthode open() :

var ouvrir_fenetre = (function() {
		var fenetre = null;
 
		return function() {
				if (fenetre == null) {
					/* Création de la fenêtre */
				}
 
				fenetre.open();
				return false;
			};
	})();

Là encore, un code assez simple : si nous n’avons pas encore créé la fenêtre, notre variable vaut toujours null, et donc nous la créons. Dans tous les cas, nous ouvrons la bête avant de terminer la fonction.

Étant donné que tout le reste du code ne bougera pas, les codes présents dans la suite de cet article seront à mettre à la place du commentaire ci-dessus. C’était un peu évident, mais autant le préciser pour être parfaitement clair.

La création d’une telle fenêtre passe par la fonction wp.media() que WordPress a créé spécialement pour nous, sans la documenter correctement pour autant. Elle admet un unique argument qui est en fait un objet contenant plusieurs paramètres utiles ou non selon la situation. Nous n’en utiliserons que 4, mais sachez qu’il y en a d’autres. Leur utilité étant cependant assez floue, je me passerai de vous les présenter.

fenetre = wp.media({
			title: 'Choisir une image',
			library: {type: 'image'},
			multiple: false,
			button: {text: 'Choisir'}
		});

Vous l’aurez compris, le paramètre « title » correspond au titre de la fenêtre, celui qui apparaît tout en haut. Il est également possible de choisir un texte pour le bouton de validation du choix avec le paramètre « button« . Attention cependant : remarquez que vous devez lui donner comme valeur un objet, et pas seulement une chaîne de caractères. Ce fonctionnement est pour le moment encore un mystère.

Avec le paramètre « multiple« , il est possible de laisser l’utilisateur choisir plusieurs fichiers ou non : à false, l’utilisateur ne peut choisir qu’un fichier, à true il peut en choisir plusieurs. Enfin, le paramètre « library » permet de restreindre le choix de l’utilisateur : avec un « type » valant « image« , l’utilisateur ne pourra choisir que des images.

Vous n’êtes bien sûr pas obligés d’utiliser tous ces paramètres, mais une personnalisation, même légère, ça peut être bien.

Si vous testez votre code, ça devrait marcher : au clic, la fenêtre des médias s’affiche comme on le voulait, tout est parfait. À une exception près : cette fenêtre ne sert à rien. Et ça c’est embêtant. Car si l’utilisateur peut uploader et choisir une image, cette sélection n’aboutit à rien. Pour cela, nous allons rajouter un gestionnaire d’événements à notre fenêtre, juste après sa création (toujours dans la condition, bien sûr) :

fenetre.on('select', function() {
		var selection = fenetre.state().get('selection').first().toJSON();
	});

La méthode on() attend deux paramètres : l’événement à gérer, et la fonction à appeler lorsque ce dernier est lancé. Tout se joue dans le contenu de cette fonction, justement : fenetre.state() va nous renvoyer un objet contenant l’état actuel de notre fenêtre. Cet objet contient la méthode get() que nous utilisons pour récupérer la sélection qui a été faite par l’utilisateur et, de cette sélection, nous ne prenons que le premier objet avec first(). Comme nous avons restreint la sélection de l’utilisateur à un seul choix, ça ne pose de toute façon pas de problème. Enfin, la méthode toJSON() permet de récupérer la sélection au format JSON, et donc sous forme d’objet, pour que ce soit plus simple à gérer.

La suite, c’est à vous de la créer ! L’objet JSON ainsi récupéré est loin d’être mystérieux : il contient toutes les informations dont vous pourriez avoir besoin concernant l’image choisie, comme son URL ou son ID. Un petit affichage du contenu de cet objet vous donnera donc ce que vous cherchez très facilement.

Pfiou ! C’était du boulot mais ce n’était, en fin de compte, pas si compliqué que ça. Une fois les bonnes informations récupérées, à vous d’en faire ce que vous voulez. Par exemple, le bouton de WP Photo Sphere récupère l’ID et l’insère dans la zone de texte. Le nombre de possibilités qui vous sont offertes ici est assez important.

Original post of Tasse de Café.Votez pour ce billet sur Planet Libre.

L’équipe de Monitoring-fr sera présente au salon Solution Linux 2014. Nous serons au stand A44 . Nous aurons quelques démos à vous faire découvrir sur les dernières nouveautés. Nous échangerons comme d’habitude avec vous sur la Supervision Open Source, l’actualité, les tendances, les technologies et bien sur du fun, …

Le Salon Solutions Linux/Open Source se tiendra au CNIT

Paris – La Défense
Hall Marie-Curie 6 Niveau C (-3)
Rue Carpeux 92800 PUTEAUX

Jours et horaires d’ouverture

• Mardi 20 mai 2014 : 9h00-19h00
• Mercredi 21 mai 2014 : 9h00-18h00

Accès

• Métro : ligne 1, station La Défense – Grande Arche
• RER : ligne A, station la Défense – Accès Parvis
• Voiture : boulevard circulaire (Parking central sortie la Défense 4 / Parking CNIT sortie la Défense 6)
• Tramway : T2 – arrêt Esplanade de la Défense – Terminus

Venez nombreux

Original post of Monitoring-FR.Votez pour ce billet sur Planet Libre.

ICANN : les USA renoncent au contrôle du DNS racine - Numerama

Edward Snowden : « La NSA met le feu à Internet, vous êtes les pompiers qui peuvent le sauver » - LeMonde.fr

Apple censure un livre pour sa couverture Numerama

L'Europe liste ses solutions pour contrecarrer les activités de la NSA - Numerama

OLPC : ça sent le sapin - Le Journal du Geek

Snowden accuse les gouvernements de « mettre le feu au futur d’Internet » - PC INpact

Every mail you send (vidéo) - jcfrog

Et si les implants médicaux étaient sous licence libre ? - LeMonde.fr

Original post of Planet Libre.Votez pour ce billet sur Planet Libre.

LibreCAD (anciennement CADuntu) est un logiciel de dessin assisté par ordinateur en deux dimensions (2D).
Il est basé sur l'édition communautaire (et libre) de QCad.
LibreCAD fonctionne sous Linux, Windows et MacOSX, dispose d'un système de plugins, d'une bonne palette d'outils et gère les fichiers DXF (et d'autres concernant les polices).

Installation :

sudo apt-get install librecad

Dernière version stable du PPA :

sudo add-apt-repository ppa:librecad-dev/librecad-stable

Dépot Daily :

sudo add-apt-repository ppa:librecad-dev/librecad-daily

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install librecad

The post Librecad un Autocad light libre et gratuit appeared first on elementary OS Fr.

Original post of SckyzO.Votez pour ce billet sur Planet Libre.