ESM import example

[codefriar]

@cesarParra - love your work.

I'm looking to incorporate apexDocs into a CI action I'm building in ESM / node. I'd like to import Apexdoxs and execute the doc generation "in-band" rather than shelling out to the cli to run apex docs. I'm struggling, however, with how and what I can import.

I've tried

import Apexdocs from '@cparra/apexdocs';

and while that will import something... it doesn't have the .generate() method on it I was expecting from the cli.

I'm sure i'm missing something obvious, but I was wondering if you could provide an example of how to import Apex docs into a typescript / esm project as a library and call it's generate method? Please?

[cesarParra]

Thanks @codefriar !

At the moment, nothing is being exported (well, that's not technically true since the index file has one export: https://github.com/cesarParra/apexdocs/blob/master/src/index.ts#L1, but that's for an undocumented feature that I've never finished implementing, so that'll go away at some point).

I can make more exports available by adding them to that index file. But first, I'd like to better understand what you are looking for to ensure the right thing is exported.

The docs output highly depends on the flags passed through the CLI (or the configuration file fallback). So I'm thinking there are 2 options. First, there can be a generate function that takes no arguments, but that'll force you to have a config file (or package.json apexdocs object) in the root directory, or it'll fail. Second, I could provide a function that takes an object representing all of the CLI settings.

There are variations to the latter option as well. For example, it could receive the contents of the files as an array of strings, and that'll provide the flexibility to the consumer to get that information from wherever they desire (I'm thinking that opens up the ability to document Apex code that resides in an org and not source control, since the contents can be retrieved through a SOQL or API call).

Then there's the question of the return type. At the moment the only output is the exit code (and the side effect is that it generates the output files, of course). So this will need to be separated as well, so that it returns an object representing the documented input instead.

[codefriar]

I, for one, would love to have a method that accepts a Settings object to the generate method. for instance:

import { ApexDocsLib } from '@cparra/apexdocs' 

// ... other setup.
public someMethod(){
  const settings = new ApexDocsLib.SettingsObj();
  settings.sourceDir = '...'
  // other settings config.
  
  ApexDocLib.generate(settings);
}  

[codefriar]

@cesarParra I'm also happy to help, if you can help me understand how the project is currently building ... I don't quite understand how the exports are built.

[cesarParra]

@codefriar

That'd be great!

I do want to point out there is a way to calling into the generate method directly right now, by going all of the way into the path where the output JS lives, something like.

import {Apexdocs} from '@cparra/apexdocs/lib/application/Apexdocs.js';

That'll give you a class back with a generate method. But that by itself would fail because the settings wouldn't be initialized.

---

Here is the general gist to setting up the project, but let me know if you'd like me to expand on anything

• Clone locally
• Run npm install
• Modify the files in the src directory
• Run npm run build to generate the output JS* The JS files will be output to a lib directory in the root folder.

*Note: if you prefer to use TS for everything and skip the build step, you can also just use the ts-node module

To test any changes in the CLI you can do that against the locally built lib file

node lib/cli/generate.js [flags]

In your case, since you want to import files then you'll want to test changes by importing it instead, for example

import * as Apexdocs from '{path_to_project}/lib/index.js';

So anything new you'd like to export can be done by modifying the src/index.ts file. In this case you can create the new generate function that takes a SettingsConfig object (as defined here: https://github.com/cesarParra/apexdocs/blob/6e104f0bc430193d91e6463734e24f88debfe0aa/src/settings.ts#L24), initialize the Settings singleton by calling its build function and then that'll make it safe to call the Apexdocs.generate function that already exists in the application folder.

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity.

[github-actions[bot]]

This issue was closed because it has been inactive for 14 days since being marked as stale.

[cesarParra]

The latest version of the tool (3.0.0) now exports a function process which does this.