Better documentation. - Githubissues

eco-infra / ecoinfra

Emission prediction tool

https://eco-infra.com

Apache License 2.0

6 stars 3 forks source link

Better documentation. #15

Closed iamdavidmt closed 5 months ago

iamdavidmt commented 6 months ago

Look into better ways to document the tool and platform as a whole.

rickwysocki commented 5 months ago

Hi there! I'm looking to build out my portfolio of documentation writing and this seems like an interesting project. Can you give any details on the type of documentation you're looking for? E.g., an OpenAPI spec file, reference documentation, a User Guide, etc?

iamdavidmt commented 5 months ago

Hi @rickwysocki - appreciate the interest! I think there's a ton of room to expand this but focusing just on the CLI tool, I'd start with this class: https://github.com/eco-infra/ecoinfra/blob/master/app/cli/main.cli.ts - documenting constrains/descriptions into the README or somewhere else more suitable (or even in code)

rickwysocki commented 5 months ago

Okay, I can try to take a look at it. I just forked the repository to see if I could get it running to test the app/that class, but I'm having a hard time finding where to create an account so I can get an API key. Can you direct me to the right spot?

iamdavidmt commented 5 months ago

Currently in closed beta, but looking to open registration in a few weeks. Maybe check out the test: https://github.com/eco-infra/ecoinfra/blob/master/tests/run.test.ts (run via npm run test)

rickwysocki commented 5 months ago

Gotcha, thanks! I'll start working on this and share some documentation/thoughts soon.

rickwysocki commented 5 months ago

Hey there: I've spent just a little bit of time detailing my understanding of the methods for this class and just wanted to check in to see whether this (screenshot below) is the direction you were hoping for with the documentation. Two questions:

Did you want more of a line-by-line description of the code in the class? As you'll see below, I took more of a user-guide approach for the arg import/methods, but am happy to revise.
The tables include an empty "use case" column. I think this would be useful but am hesitant to come up with use cases since I can't try the application myself yet. Do you think this is a useful idea and, if so, do you have any thoughts about use cases for those methods?

Of course, feel free to point out any errors I've made or any other feedback you have. Thanks for letting me work on this!

iamdavidmt commented 5 months ago

This looks great @rickwysocki - I suggest we create a docs directory and we can put documentation in there.

rickwysocki commented 5 months ago

Okay, I just submitted a PR. Depending on the amount of documentation you anticipate, I would recommend setting up a documentation site for organizing content. I did a quick setup of that on a different branch locally (using Jekyll) and included a screenshot of the result below. If you think that's something you'd be interested in, I'd be happy to get the docs site configured. I believe it should be able to be run out of the repository using a /docs folder as the source for GitHub pages. 2024-04-01_12-01-05

iamdavidmt commented 5 months ago

I think that's a great idea - lets create a new issue and brainstorm some ideas and set something like this up.

github-actions[bot] commented 5 months ago

:tada: This issue has been resolved in version 1.14.0 :tada:

The release is available on GitHub release

Your semantic-release bot :package::rocket: