search

ioos / model-data-framework

Documentation, tools and issues for implementing standardized tools for working with model data (data output from models)
Creative Commons Zero v1.0 Universal
2 stars 0 forks source link

How should I document the model data framework? #2

Open rsignell-usgs opened 8 years ago

rsignell-usgs commented 8 years ago

I would like to document the installation, configuration and maintenance of the many moving pieces of the model data framework here.

My plan was to edit the wiki, and use the mkdocs approach to generate nicer looking github pages.

After reading the discussion here https://github.com/ioos/conda-recipes/pull/744 I'm not sure this is the best approach.

@abirger or @ocefpaf, what is the recommended approach?

rsignell-usgs commented 8 years ago

ping @abirger

abirger commented 8 years ago

@rsignell-usgs , it's not clear at the moment. The main issue that we are trying to deal with is that MkDocs has pretty scarce choice of themes, and neither of them currently can replicate the layout and/or color scheme of the existing IOOS sites. The Hugo's Lanyon theme had been chosen because it provides a sliding sidebar function that allows more screen space for the texts. All MkDocs themes keep a static sidebar that takes away about 1/3 of the page width - it may be OK for a blog but is pretty bad for documentation. On the other hand, MkDocs is simpler, generation and deployment GitHub Wiki pages is easier, and the required folder/file structure is cleaner. So, if we can modify an MkDocs theme to match the Lanyon layout including the hiding sidebar, the MkDocs will win hands down. Unfortunately, I am pretty lame-brained in css, so the modification goes ahead slowly...

ocefpaf commented 8 years ago

@rsignell-usgs , it's not clear at the moment. The main issue that we are trying to deal with is that MkDocs has pretty scarce choice of themes, and neither of them currently can replicate the layout and/or color scheme of the existing IOOS sites. The Hugo's Lanyon theme had been chosen because it provides a sliding sidebar function that allows more screen space for the texts. All MkDocs themes keep a static sidebar that takes away about 1/3 of the page width - it may be OK for a blog but is pretty bad for documentation. On the other hand, MkDocs is simpler, generation and deployment GitHub Wiki pages is easier, and the required folder/file structure is cleaner. So, if we can modify an MkDocs theme to match the Lanyon layout including the hiding sidebar, the MkDocs will win hands down. Unfortunately, I am pretty lame-brained in css, so the modification goes ahead slowly...

Rich,

Alex pretty much summarized where we are now. I am not a CSS expert, but I think we can get results similar to Hugo tweaking the readthedocs theme and go with MKDocs.

I disagree only about the side bar. I like the permanent one and, even if we can get rid of it, I don't want the text to spread horizontally too much. It is not good for reading.

BTW, regardless if the tool, you can start writing the Markdown files. They will be essentially the same in any tool we end up choosing. (Hugo requires a header that can be inserted later.)

Regarding the files, I prefer if you write them in the repo, using PRs, rather than using the wiki. That way we make the tracking clear (and I won't need to create the files for the page later.)

abirger commented 8 years ago

@ocefpaf , @rsignell-usgs , I compiled a skeleton of a generic IOOS documentation web site for rendering with Hugo. Just add those files and folders to the local copy of your repo; put the markdown docs (with proper "headers"/front matter) into content folder; modify config.toml for your site name, URL, etc.; render the site with Hugo; and finally run the deploy.sh script. That's it, you are done.

I disagree only about the side bar.

I was somewhat indifferent at first, and then Shane single-handedly convinced me that the document shall be seen in full page mode. Perhaps, we need more opinions on this matter...