Help Wanted: Documentation

[jonschlinkert]

Earlier today, #24 was published as 2.0 with the beta tag! The only thing stopping us from merging to master and publishing 2.0 is documentation.

If you'd like to help with docs (readme documentation only, for now), here is an outline of what we need:

• A section for the Enquirer class. Enquirer itself can be viewed as the prompt "runner". It handles state and events for multiple prompts, etc.
• A section for the base Prompt class - The Prompt class creates the readline interface, handles keypress events, and other conveniences that simplify creating custom prompts. The Prompt class is inherited by every other prompt.
• A section for each base prompt type in the lib/types directory. The types - string, number, boolean and array - are classes that can be extended to create higher level prompts. For example, the Input prompt class inherits the StringPrompt class, and the Select prompt inherits the ArrayPrompt class. This approach makes prompts extremely simple to create, extend, and customize. The type classes are just a convenience, and don't need to be use if you'd rather just extend the base Prompt class.
• A section for each prompt in the lib/prompts directory.
• A table or list of the available options for each prompt. Most prompts support the same global options, like message, name, etc. We can list these with the base Prompt class. Then in the docs for each prompt we only need to list the special options supported that prompt.
• Usage examples (you can find many examples in the examples directory)

Other stuff

• blog posts
• tutorials
• tweet about 2.0!

We encourage you to tell your friends and write about Enquirer! We're really excited about how awesome Enquirer 2.0 is, and we think you'll love it too!

[swashata]

Hi,

I created a gatsbyjs template for documentation. Here you can see https://wpack.io and here's the repo https://github.com/swashata/wp-webpack-script/tree/master/site I can create a starter template out of it, or even help you in implementing.

For the docs itself I will this it out to replace inquirerjs and maybe I could be of help.

[g-plane]

I recommend to use VuePress to write the docs.

[jonschlinkert]

readme documentation only

Thanks for the comments. We want documentation to be complete first. At the moment, technical writing is what we need help with most.

[jondot]

@jonschlinkert is enquirer direct swap for inquirer? so far i'm seeing that the answer is "Yes" but cannot see this documented anywhere -- and would be really worthwhile to document that.

[g-plane]

Maybe we can create a new repository as enquirer/enquirer.github.io, then we can put the documentation in it. Also, we can register a domain enquirer.js.org. (It's free!)

[jonschlinkert]

@g-plane I haven't decided yet where we're going to put the docs. We might do what you're suggesting. First I want to get the markdown documentation finished since that doesn't require a website and (IMHO) it's easier to just focus on content until it's complete.

Also, we can register a domain enquirer.js.org. (It's free!)

I already have enquirer.io :) we'll be using that. Good idea though!

[g-plane]

Good points. And we can use documentation tool to generate static website for better reading experience.

[pixelass]

@jonschlinkert If you are interested in guides similar to this: https://stickyroll.github.io/react-stickyroll/doc/guide/configue-stickyroll/Readme.html?guides-enabled=true

I'd love to help writing these guides. It should be basic markdown so it can then be used in whatever tool to display it nicely.

[jonschlinkert]

If you are interested in guides similar to this: https://stickyroll.github.io/react-stickyroll/doc/guide/configue-stickyroll/Readme.html?guides-enabled=true

Yes that would be great! Any help would be appreciated!

[pixelass]

I'll see if I can whip up an example. No promises, gotta study the new API first.

[pixelass]

@jonschlinkert I'm not sure if this is what you're looking for:

https://github.com/pixelass/enquirer/blob/docs/form-example/docs/prompts/form/getting-started.md

[jonschlinkert]

@pixelass that's great! I love it! Thank you!

[pixelass]

@jonschlinkert Glad to hear. I can continue in this manner (starting with forms since I'm currently using it in a setup).

I will probably run into issues and my guides will require a good review to ensure the validity (haven't used this in a while) but these guides are small enough to review on the go and write during small breaks (Hoping to eventually encourage more contributors to the docs). I can pick a lot of info from the old examples but updating those would go into another PR (out of scope)

I'll try to get the forms done as good as I can before I send in the first PR.

[jonschlinkert]

Great! FWIW all of the examples in the examples folder are for the current version of Enquirer. If you find one that is broken, please feel free to just create an issue instead of trying to fix it, or handle it however you prefer. I also have some higher level docs created locally, for things like styling. If you want to do a PR with you docs first, I can merge those in before pushing up my changes. Thanks again!

…

Sent from my iPhone

On Dec 13, 2018, at 7:19 AM, Gregor Adams ***@***.***> wrote: @jonschlinkert Glad to hear. I can continue in this manner (starting with forms since I'm currently using it in a setup). I will probably run into issues and my guides will require a good review to ensure the validity (haven't used this in a while) but these guides are small enough to review on the go and write during small breaks (Hoping to eventually encourage more contributors to the docs). I can pick a lot of info from the old examples but updating those would go into another PR (out of scope) I'll try to get the forms done as good as I can before I send in the first PR. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[pixelass]

@jonschlinkert I know that the example for form uses the old API: https://github.com/enquirer/enquirer/blob/master/examples/form/prompt.js

const { Form } = require('enquirer');

as do some others (probably all those that used to have named exports).

[jonschlinkert]

I’m not sure what you mean. That API is current. (Also, the Form prompt was created for Enquirer v2.0, so it couldn’t have been used that way before). Each prompt is set as a static method on Enquirer, in case you need access to a prompt instance. edit: to elaborate (or maybe as a reminder), in the old, Enquirer v1.0 API all of the prompts were separate libraries that needed to be registered first.

[jonschlinkert]

In case it helps:

• here is where each prompt class is added as a static method.

  const { Form } = require('enquirer');
  const form = new Form({
    name: 'config',
    message: 'Configuration settings',
    choices: [...]
  });
  
  let answer = await form.run();
  console.log(answer);

• and here the prompt instances are made available as static methods

  const enquirer = require('enquirer');
  
  let answer = await enquirer.form({
    name: 'config',
    message: 'Configuration settings',
    choices: [...]
  });
  
  console.log(answer);

[pixelass]

Thanks for the info.

Maybe my issue was related to typescript. I remember looking at the typings and not finding the static properties.
I then found this: #32 (comment) (which led me here).
I must have misread it and assumed my previous statement based on the success I had by setting the type as an option property and my quick glance at the type definitions (I skimmed it rather late at night).

Any info on the type definitions? Are those up to date?

I'll test this later and consider this when writing the guides (I obviously need to adjust the first one).

[doowb]

I then found this: #32 (comment) (which led me here).

Someone read what I wrote!!! 😀

I said it was recommended because, at the time, all of the examples in the README used the prompt method and we haven't gotten to documenting that the built-in prompt classes are exposed as static properties yet.

Any info on the type definitions? Are those up to date?

There's PR #82 open right now that might address those.

[jonschlinkert]

@pixelass your guide is awesome, I'm appreciative that you're helping. @doowb and I are of course happy to do editorial stuff like fixing typos or variables/references if we find any that are wrong. Don't worry too much about that.

[pixelass]

@doowb thx for the info. That explains the misunderstanding.

@jonschlinkert You're right, I'm not worried, I just want to get a few things straight. (Would hate to have to modify guides later).

My questions were answered. I'll continue and send in PRs as smaller batches.

[pixelass]

I was thinking about adding new recordings (via svg-term).

It returns an SVG (instead of gif) which has impact on the rendering performance of the sites using it (e.g. the main Readme.md)

I would also like to add these to each guide I create. (the examples created in this guide will be located in a separate directory guides and eventually replace examples. This way each guide has a working example to execute.

It's also good to know the guides provide working code instead of blindly written snippets.

[mikeerickson]

Hey gang, if you need any additional resources, I would be happy to help. I don’t want to step on toes or intrude, but I can assist

[pixelass]

@mikeerickson look at PR #99 This is probably what we'll be going for.

Since the docs are already split into sections you could just follow the examples and add a new folder (prevents conflicts before the fist merge).

I added some tools for screencasts (asciicast) which need to be integrated in a better way (I'm thinking gh-pages file hosting https://enquirer.github.io/media).

@jonschlinkert @doowb opinions on having a separate repo for docs?

[mikeerickson]

@pixelass I will have a look at this in the morning

[jonschlinkert]

opinions on having a separate repo for docs?

Yeah, I think we touched on this somewhere else, maybe another issue. Just for now I'd like to keep everything together. Once the markdown docs are more comprehensive and we start designing the site, we might switch to another repo.

[jonschlinkert]

Hey gang, if you need any additional resources, I would be happy to help. I don’t want to step on toes or intrude, but I can assist

Any additional help would be awesome!

[pixelass]

Once the markdown docs are more comprehensive and we start designing the site, we might switch to another repo.

My new PR already accounts for this. I agree that the focus right now is getting more docs written.

[roblav96]

@jonschlinkert @pixelass @mikeerickson
You all are doing an absolutely fantastic job producing the content for the docs! 🤗

I've just spent a solid hour reading as much as I could and plaid around with the examples provided. There's plenty of content to get an understanding of how to use this, but it's scattered all over the place and repeated multiple times in different folders. Some consolidation into a gitbook, github wiki, or vuepress is needed.

This project is a game changer! So responsive, easy to understand, great UX for the terminal. Bravo all around my friends =]

[pixelass]

@roblav96 thx for the kind words. Once we have more content we will move to a library to make the info easily accessible. Right now the focus is creating more content and matching examples. There won't be too much discussions about wiki-libraries though. We will use what makes sense once we have a bigger picture.