search

OSeMOSYS / otoole

OSeMOSYS Tools for Energy
https://otoole.readthedocs.io
MIT License
23 stars 17 forks source link

Documentation Update #137

Closed trevorb1 closed 1 year ago

trevorb1 commented 1 year ago

Hi, this is a draft PR.

In this PR I begin updating the documentation in preparation of the otoole v1.0 release. Using Issues #107 and #113 as reference, I have attempted to clearly explain the conversion, result and visualization commands, and provide examples. As part of this process, I reorganize the navigation of the site and break "Core Functionality", "Data Standards" and "Examples" into three separate pages. Moreover, as per issue #135 I remove references to the datapackage.

To build and view the site on your local machine:

  1. Checkout the branch docs-update
  2. Build the docs with tox -e docs
  3. Run the command python3 -m http.server --directory 'docs/_build/html'

I am definitely not married to the structure I have proposed. I just wanted to get the ball rolling on updating the docs and get feedback if anyone has any! :)

Finally, this is very much a draft PR and should only be pushed when v1.0 is ready. For example, the viz res command in this PR says to use a datafile, while in the current version (v0.11.0) it requires a datapackage. So things like that assume the code is at v1.0.

Thanks!

trevorb1 commented 1 year ago

This docs update is getting close to being done! A couple quick things I wouldn't mind a second opinion on though please, @willu47:

  1. I have added tables to the documentation with examples on how to format excel data and csv data. Do you think I should also include screenshots, or will that be overkill? Or maybe just link to the Simplicity repository if they want a concrete example? (This relates to both issue #107 and issue #113). Here is an example of what the tables in the docs currently look like.

Time Dependent Parameter image

Time Independent Parameter image

  1. I separated all examples and core functionality into two separate pages. I think this made everything more clear, but just want to get a second opinion on this, please! :)
  2. I took a shot at redoing the opening image that describes otoole, however, I don't think it looks all that clear haha. I did this because I moved the workflow image to the Core Functionality page. Do you think its okay, or if you have suggestions on how to improve the image, that would be great! Or we can just have the same workflow image in both places if we think that is the most clear

Homepage Image image

Core Functionality Image image

Thanks so much!!

willu47 commented 1 year ago

Hi @trevorb1 - this looks great. I suggest to avoid using screenshots. They have a habit of being outdated quickly, and are a more of a pain to update than the inline tables.

I think the new visuals look very nice and are a big improvement on what was there before.