BASIN-3D/basin3d

Refactor project README.md structure

Closed this issue · 5 comments

vchendrix commented

Refactor REAMDE.md structure to be more user friendly.

  • New README.md structure
    • project name (README.md)
    • description (README.md)
    • link to documentation website (README.md)
    • installation instructions (README.md)
    • Link to how to contribute (CONTRIBUTE.md)
    • Change log (CHANGES.md) - with the 2 versions and releases
    • Authors
    • License (LICENSE.md)
    • Copyright (README.md)
    • Acknowledgements (README.md) - make comment and ask charu
  • Update license file (to with repostory name)
  • Add a contributing file with getting started for developers. (add dev practices, documentation, testing, etc.)
  • Update setup.py with updated information
  • Setup github io docs (moved to separate ticket)
setup(name='basin3d',
      version=__release__,
      description='BASIN-3D Core Framework',
      long_description=README,
      author='Val Hendrix, <list all authors>',
      author_email='vchendrix@lbl.gov, <list all author emails>',
      url='https://github.com/BASIN-3D/basin3d',
      packages=packages,
      data_files=['basin3d/data/basin3d_variables_hydrology.csv',
                  'basin3d/plugins/mapping_usgs.csv'],
      include_package_data=True,
      install_requires=[
         "pandas",
         "pyyaml",
         "requests",
         "tinydb"
      ]
      )
heycatwonton commented

@vchendrix @dschristianson

In order for Github Pages to work:

  1. Create an empty .nojekyll file in the docs directory (root) to turn off Jekyll.
  2. Create index.html file in the docs directory (root) with contents:
  • <meta http-equiv="refresh" content="0; url=./docsrc/html/index.html" />
  1. Create seperate directory docsrc, to build documentation and add docsrc directory to repo
  2. Change the Sphinx build directory to documentation in your Makefile:
    BUILDDIR = docsrc
  3. Run make html
  4. add, commit and push:
  • docsrc/
  • index.html
  • .nojekyll
  • Makefile
  1. In Settings -> GitHub Pages -> Source -> choose <branch>/docs
  2. Visit https://heycatwonton.github.io/basin3d/

Notes: _build and build are both directories .gitignore will ignore. As you know, ignored files cannot be tracked and added to git. Without adding the actual documentation after build, Github Pages is unable to reference and host them. I used docsrc as the directory for building the docs but can be changed to something else.

Source: sphinx-doc/sphinx#3382

heycatwonton commented

TODO: pip install directory from repo

heycatwonton commented

@charuleka We are working on the basin3d README file, and below is Acknowledgments. Does this look right to you or are there any edits you'd like to make?

Acknowledgments
This research is supported as part of the Watershed Function Scientific Focus Area funded by the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research under Award no. DE-AC02-05CH11231. This research used resources of the National Energy Research Scientific Computing Center (NERSC), U.S. Department of Energy Office of Science User Facility operated under Contract No. DE-AC02-05CH11231.

charuleka commented
heycatwonton commented

edit: closing manually but issue would've been closed after branch is merged to main (not release)