This is my first time been asked to write a documentation and my choice of way to do it is by using jsdoc.
This following is the sample jsdoc.json config file for my jsdoc. It read just a single README.md file.
{
"source": {
"include": "./client/src",
"includePattern": ".js$",
"excludePattern": "(node_modules/|docs)"
},
"plugins": ["plugins/markdown"],
"templates": {
"cleverLinks": true,
"monospaceLinks": true,
},
"opts": {
"recurse": true,
"destination": "./docs/",
"readme": "./README.md"
}
}
How can I make it to read multiple .md file like if I have index.md and content.md?
I just wanted to do the same functionality, and the approach that I found is not perfect, but it works good enough.
In JSDOC there is an functionality called "tutorials".
What I have done, is created on the root of my project folder "Tutorials" and added to the "opts" section in my config file the following:
"opts": {
"tutorials": "./Tutorials",
}
In the tutorials folder you create as many .md files you need, keeping in mind that every tutorial needs to have unique name.
Every time you want to connect something with specific tutorial (for example tutorial called "content.md") you need to put
{#tutorial content}
This works in both Readme.md and any js file you have documentation. Also you can connect one tutorial with another.
you can learn more about the feature here:
https://jsdoc.app/about-tutorials.html
https://jsdoc.app/tags-inline-tutorial.html
my answer is a bit late, but I hope this can at least help you for future projects :)
Related
How do I work with node modules?
tldr; How do I look at a node module I've installed and know where to go and what I'm looking for
If I use npm i googleapis for example, it downloads the node module for Googles APIs but how do I browse the module and work out what's useful for me?
To try and eliminate any ambiguity from the question, I'll use this use case.
I'm developing a Discord bot and I want to add statistics to one of
the commands. Here is the supplied code from Google:
<script src="https://apis.google.com/js/api.js"></script>
<script>
/**
* Sample JavaScript code for youtube.channels.list
* See instructions for running APIs Explorer code samples locally:
* https://developers.google.com/explorer-help/code-samples#javascript
*/
function authenticate() {
return gapi.auth2.getAuthInstance()
.signIn({scope: "https://www.googleapis.com/auth/youtube.readonly"})
.then(function() { console.log("Sign-in successful"); },
function(err) { console.error("Error signing in", err); });
}
function loadClient() {
gapi.client.setApiKey("YOUR_API_KEY");
return gapi.client.load("https://www.googleapis.com/discovery/v1/apis/youtube/v3/rest")
.then(function() { console.log("GAPI client loaded for API"); },
function(err) { console.error("Error loading GAPI client for API", err); });
}
// Make sure the client is loaded and sign-in is complete before calling this method.
function execute() {
return gapi.client.youtube.channels.list({
"part": [
"snippet,contentDetails,statistics"
],
"id": [
"UC_x5XG1OV2P6uZZ5FSM9Ttw"
]
})
.then(function(response) {
// Handle the results here (response.result has the parsed body).
console.log("Response", response);
},
function(err) { console.error("Execute error", err); });
}
gapi.load("client:auth2", function() {
gapi.auth2.init({client_id: "YOUR_CLIENT_ID"});
});
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>
Now Google offers a supported library which means I can replace the external script tags and import from the node package, specifically the parts I need.
So I'll need to import or require whatever gives me access to things like:
gapi.auth2.getAuthInstance
gapi.client.setApiKey
gapi.client.youtube.channels.list
For someone who is new to nodejs, instead of copy and pasting from every piece of documentation and hoping it works, how do I comfortably look at a node package and find the things I need and can use?
Edit #1
I think my use of the google apis case threw off the direction of the question and changed the scope of what I asked so I'm going to correct the best I can.
The assumption should be made that there is no documentation on the package whether it's so poorly written, doesn't exist at all or the documentation is down for an extended period of time during a time sensitive development.
At that point, is there any possible way to look at the node_modules folder, the specific package that needs to be worked with and work out what's going on? Is there any way to look at the structure of a package and recognise "well most likely what I need is in this folder or file"
That's what documentation is for.
When someone writes an API for a package; to make things clearer for the consumer, he should document the exported functions well enough.
The best way to get the documentations for node packages is to search for the package at www.npmjs.com .
For google apis you can go to that page here to see the "get started" and some examples. And you can go here to see the full detailed APIs of that package.
Answering Edit #1
Well, in that case, it could be a difficult task, depends on the how structured and organized the package is.
Since we are talking about nodejs, you should look for the package.json file and search for the path of the main file "main": "<PATH HERE>".
Then, you can go to that main file and try to locate what exactly is being exported. You can search for module.exports or the export keyword.
Everything that is explicitly exported is intended to be used as an API.
I'm not familiar with any other way other than go deeper in the package's files and identify what exactly is being exported.
I have installed angular universal on my app.
Running npm run build:ssr - DONE. WORKS.
Running npm run server:ssr - DONE.WORKS.
After accessing the server URL (localhost:4000), the page is not fully loaded and the following error is raised on the Terminal:
I also faced the same problem, so I would just like to share my findings for the same.
For me, there were two plausible causes/solutions for it:
First, in my project's I18N default JSON file that was en.json, I was having a problem In the structure of the JSON file.
For example, I had the below mistake. I missed the comma after the second label 'FINISH' :
{
"COMMON": {
"EDIT": "Edit",
"FINISH": "Finish"
"QUIT": "Quit",
}
}
So after correcting the structure, the application ran fine without an error.
Secondly, another cause of the issue could be, at runtime transloco was not able to find the correct label in the selected language, so it looked for a fallback language and it could not even find that in the transloco-root.module.ts so after adding my fallback language, it tried to find the same in the fallback language as specified in the transloco-root.module.ts.
So it found out that label and the issue got resolved.
BUT in the second solution provided, you need to have that incorrect label in at least that fallback language's json file in correct format.
I added the fallback language like below:
useValue: translocoConfig({
availableLangs: ['fr', 'en'],
defaultLang: 'en',
reRenderOnLangChange: true,
fallbackLang: 'fr',
prodMode: environment.production,
missingHandler: {
logMissingKey: true
}
})
i18n Transloco wasn't fully configured on the module file.
I am new to VS code (1.21.1) with HIE 0.1.0.0 - installed using stack. I have been able to define a task for testing:
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": [
{
"label": "test",
"type": "shell",
"command": "stack build --test",
"group": {
"kind": "build",
"isDefault": true
}
}
]
}
I checked the documentation mentioned but did not understand much.
This task works only on the project I specified it for; how to make it usable for any project I happen to have open in the editor? How to further automate the selection of tasks?
I assume that there is somewhere a collection of tasks to run stack with HIE - could somebody point me to it?
I'm not sure if this is the problem you run into, but Visual Studio Code gives you the ability to edit settings per work-space/project in addition to overall settings:
Make sure that you're editing the USER SETTINGS tab instead of the WORKSPACE SETTINGS tab, if you want the settings to all projects.
Apologies if this is a trivial answer, and the problem is something completely different.
I am trying to convert an existing JS project currently using Grunt for building project over to Brunch.
I'm initially trying to make brunch work using existing directory structure.
app
- images
- less
- scripts
I want to copy the images into public directly (ie. as assets).
I know I could move them to app/assets/images but I prefer not to change the structure yet.
brunch-config.js:
module.exports = {
conventions: {
assets: [ '^(?:app)/(images/**/*)' ],
// assets: [ /(?:^app\/images[\\/])/ ],
// assets: [ '(images/**/*)' ],
//assets: /images[\\/]/,
}
}
I want the image files to get copied to public/images.
ie. keep the "images" directory name
But the best I can seem to manage (using that uncommented assets value) is copying to public/app/images.
The other attempts just copy the contents of app/images to public.
ie. so i get app/image.jpg instead of app/images/image.jpg
I was hoping the using the non-captureing grouping of the "app" part in the regex would maybe make it work, but didn't.
Any ideas ? Thanks
this is a way late response but I've created a plugin for this called https://www.npmjs.com/package/copycat-brunch that helps you configure brunch and mantaining your file directory structure, it's all in the README
plugins:{
copycat:{
"fonts" : ["bower_components/material-design-iconic-font", "bower_components/font-awesome/fonts"],
"images": ["someDirectoryInProject", "bower_components/some_package/assets/images"],
verbose : true, //shows each file that is copied to the destination directory
onlyChanged: true //only copy a file if it's modified time has changed (only effective when using brunch watch)
}
}
Leaving this here in case it helps some else too :)
In my wintersmith-built site, I want to have:
index.html containing a news feed
blog.html containing a blog index
I copied paginator.coffee into newspaginator.coffee, tweaked it to return 'news' instead of 'articles', and with a couple of other adjustments, it works fine.
Then I tried to add the original paginator back in, with some parameters in config.json:
"plugins": [
"./plugins/newspaginator.coffee",
"./plugins/paginator.coffee"
],
"newspaginator": {
"articles": "news",
"perPage": 10
},
"paginator": {
"articles": "articles",
"template": "blog.jade",
"first": "blog.html",
"filename": "blogpage/%d/index.html",
"perPage": 3
}
Now: I only get the HTML page for whichever plugin comes second. As above, I get blog.html but no index.html. If I reverse the order of the two plugins, I get index.html but no blog.html.
How do I get it to do both?
There's a few wintersmith properties that paginator.coffee sets that need to be accounted for in your "tweaks" or one plugin will override the settings of the other. Here are the ones I've noticed:
options = env.config.paginator or {}
...
env.helpers.getArticles = getArticles
...
env.registerGenerator 'paginator', (contents, callback) ->
Take env.helpers.getArticles for example. Somewhere in your templates you'll call something like env.helpers.getArticles(contents). That will be the method for whichever plugin is called second, since the second plugin overrides the value that the first set.
You should be able to get it to work by changing those three lines. This is still a bit of a hacky solution, since you're duplicating code (DRY Principles) but it could be a good quick fix since it doesn't seem the paginator plugin was set up to work on more than one directory.