Question Texte et contenu "Home" par défaut pour JSDoc


Après avoir exécuté une compilation / rendu JSDoc de base depuis Node.js:

jsdoc file1.js file2.js

Je reçois un document bien formaté en utilisant le modèle par défaut dans un répertoire "out". Presque tout est comme prévu!

Mais lorsque vous ouvrez le document, il affiche toujours "Home" sur la page index.html, n'a aucun contenu sur cette page initiale et affiche "Home" dans la barre de navigation.

Comment et où puis-je noter le nom du projet pour qu'il remplace "Home"? J'aimerais également voir une description du projet, ainsi que des informations sur l'auteur et le copyright.

Il semble que ce soit le plus fondamental des choses à faire dans un JSDoc, mais je ne trouve pas l'information! J'ai essayé ce qui suit, basé sur un article que j'ai trouvé sur Internet:

/** 
 * This JavaScript file contains foo bar baz...
 * 
 * @projectname Project Name
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

Mais je n'ai pas d'amour.

[édité pour ajouter:]

Découvert la directive @file / @fileOverview / @overview (tous les synonymes), ce qui est plutôt utile car je peux maintenant décrire et définir les informations de copyright / auteur pour chaque fichier:

/** 
 * @file Project description which renders below the individual filename and therefore isn't a real overview blurb.
 * 
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

Cela laisse 2 "problèmes" à résoudre encore:

  1. Une description générale; Je pense que @file prend en charge la plupart de mes besoins, mais comme il s’agit d’un fichier par fichier, j’aimerais toujours un paragraphe de type «introduction» ou un paragraphe d’aperçu qui apparaît avant la description des fichiers inclus.

  2. Remplacement du texte "Accueil" par un texte personnalisé


13
2018-06-08 18:26


origine


Réponses:


Générer la page d'accueil

Créer un fichier de démarques README.md

Générer jsdoc:

$ jsdoc path/to/js path/to/readme/README.md

Pour en savoir plus sur cette visite documentation officielle

Changer le texte 'Home'

Je ne pense pas que ce soit une bonne façon de le faire, mais cela fonctionne.

Si vous avez installé jsdoc dans votre fichier de modèle de recherche de projet dans votre répertoire de travail, le mien était:

./node_modules/jsdoc/templates/default/publish.js

Ensuite, recherchez "Home" avec la commande de recherche et remplacez-le par votre texte, la prochaine étape consiste à spécifier le modèle lors de la génération de jsdoc:

 $ jsdoc ./src/scripts/ ./README.md -t node_modules/jsdoc/templates/default/

15
2018-06-09 12:20



Je ne peux pas commenter alors je vais ajouter une note ici pour clarifier comment faire toutes les choses dans la question d'origine sans modifier le modèle par défaut, basé sur les instructions dans un fichier trouvé dans le \ npm \ node_modules \ jsdoc \ "templates", qui explique comment créer vos propres modèles. Les étapes à suivre pour modifier les en-têtes "Accueil" de la documentation js générée afin de projeter des en-têtes spécifiques (par exemple, "MyDescription") et inclure le texte de présentation en haut de la page principale sont décrites ci-dessous.

Pas

  1. Tout d'abord, pour obtenir la vue d'ensemble en haut de la page principale de la documentation de js, vous devez écrire le fichier texte simple nommé README.md dans Markdown conformément à la réponse et au lien ci-dessus. Le texte entier apparaît en haut de la page si le chemin d'accès à ce fichier est inclus dans la ligne de commande comme indiqué ci-dessus ou si une référence est ajoutée dans un fichier nommé conf.json, auquel cas vous pouvez utiliser jsdoc -c pathTo\conf.json pour la ligne de commande (voir exemple au point 4 ci-dessous). (Comme l'explique le lien, vous pouvez créer un fichier avec n'importe quel nom ou extension tant qu'il est dans Markdown et que vous indiquez à jsdoc où le trouver).
  2. Copiez le dossier et le contenu du modèle par défaut (\npm\node_modules\jsdoc\templates\default) dans un nouveau répertoire, en renommant le nouveau dossier en quelque chose comme myTemplate.
  3. En utilisant les conseils ci-dessus pour Changer le texte 'Home', recherchez le fichier nommé publish.js à l'intérieur du nouveau myTemplate dossier et remplacer "Home" par "MyDescription". Deux points à noter ici: le nom du fichier doit rester publish.js, et "Home" est apparu à deux endroits dans mon "publish.js" original, dans la ligne
    var nav = '<h2> <a href="index.html"> Accueil </a> </ h2>';
     et la ligne commençant generate('Home',....
  4. Indiquez au générateur jsdoc où trouver votre modèle personnalisé (myTemplate dossier) et votre fichier de vue d'ensemble ("README.md"). Vous pouvez ajouter -t pathTo\myTemplate à la ligne de commande, ou vous pouvez utiliser une ligne de commande très courte, jsdoc -c pathTo\conf.json si vous créez un fichier nommé conf.json dans un éditeur de texte, quelque chose comme le fichier ci-dessous, qui spécifie la source, la destination, etc. pour la documentation. Ce fichier met l'aperçu dans la page principale en indiquant au générateur de documents à utiliser README.md dans la section "source", et change les titres de "Home" à la nouvelle rubrique "MyDescription", en utilisant le nouveau myTemplate dossier dans la section "opts".

    {
        "tags": {
            "allowUnknownTags": true,
            "dictionaries": ["jsdoc","closure"]
        },
        "opts": {
            "template": "pathTo/myTemplate",
            "destination": "pathTo/myJScriptDocs",
            "recurse": true
        },
        "source": {
            "includePattern": ".+\\.js(doc)?$",
            "excludePattern": "(^|\\/|\\\\)_",
            "include": ["pathTo/myJSSources", "pathTo/README.md"]
        },
        "plugins": [],
        "templates": {
            "cleverLinks": false,
            "monospaceLinks": false
        }
    }
    

4
2017-08-08 05:11



Vous pouvez également ajouter un @file (ou @fileOverview) à un ou plusieurs de vos fichiers sources.

Toutes les sections de la vue d'ensemble des fichiers seront incluses dans la page d'accueil de JSDoc. Si vous envoyez également votre fichier README à JSDoc, les aperçus des fichiers seront placés après le contenu du fichier Lisez-moi.

Exemple:

/**
 * @file index.js is the root file for the example.
 * It kicks things off.
 * @author Your name goes here
 * @see <a href="https://developers.docusign.com">DocuSign Developer Center</a>
 */

2
2018-05-08 11:56



"Home" est harcodé (passé comme title lors de la génération de l'index) dans le modèle par défaut, il n'y a donc pas de variable ou de configuration que vous pouvez définir pour modifier ce titre.

Si plusieurs personnes génèrent / modifient les documents, éditez le fichier node_modules est un non-aller évident.

Il suffit de créer un layout.tmpl (ou un template personnalisé complet, si vous en utilisez un), de lui pointer JSDoc (option CLI ou fichier de configuration) et de remplacer <?js= title ?> avec <?js= title==='Home' ? 'Your Title' : title ?>.


1
2017-09-13 09:55