From 431128ff05d442f246658eb8886a4248e21f13f0 Mon Sep 17 00:00:00 2001 From: Brandon Barker Date: Thu, 26 Sep 2024 16:13:20 -0400 Subject: [PATCH] attempt 1 at sphinx docs --- .github/workflows/docs.yml | 41 +++++++++ doc/index.html | 10 +++ doc/sphinx/.gitignore | 1 + doc/sphinx/Makefile | 20 +++++ doc/sphinx/conf.py | 43 +++++++++ doc/sphinx/index.rst | 31 +++++++ doc/sphinx/make.bat | 35 ++++++++ doc/sphinx/src/code_of_conduct.rst | 76 ++++++++++++++++ doc/sphinx/src/contributing.rst | 88 ++++++++++++++++++ doc/sphinx/src/governance.rst | 137 +++++++++++++++++++++++++++++ doc/sphinx/src/sphinx-doc.rst | 134 ++++++++++++++++++++++++++++ 11 files changed, 616 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 doc/index.html create mode 100644 doc/sphinx/.gitignore create mode 100644 doc/sphinx/Makefile create mode 100644 doc/sphinx/conf.py create mode 100644 doc/sphinx/index.rst create mode 100644 doc/sphinx/make.bat create mode 100644 doc/sphinx/src/code_of_conduct.rst create mode 100644 doc/sphinx/src/contributing.rst create mode 100644 doc/sphinx/src/governance.rst create mode 100644 doc/sphinx/src/sphinx-doc.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..a77aa93c --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,41 @@ +name: Build and Deploy docs + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + release: + types: + - created + +jobs: + docs: + name: build and deploy docs + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + with: + fetch-depth: 0 + - name: Set system to non-interactive mode + run: export DEBIAN_FRONTEND=noninteractive + - name: install dependencies + run: | + pip install sphinx + pip install sphinx-rtd-theme + pip install sphinx-multiversion + - name: build docs + run: | + echo "Repo = ${GITHUB_REPOSITORY}" + cd doc/sphinx + # throw warnings as error to make sure docs properly build + make multiversion SPHINXOPTS="-W --keep-going -n" + - name: Deploy + if: ${{ (github.event.pull_request.head.repo.full_name == github.repository) || (github.ref == 'refs/heads/main') }} + uses: peaceiris/actions-gh-pages@v3.7.3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./doc/sphinx/_build/html + force_orphan: true diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 00000000..0eb51097 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,10 @@ + + + + + Redirecting to develop branch + + + + + diff --git a/doc/sphinx/.gitignore b/doc/sphinx/.gitignore new file mode 100644 index 00000000..e35d8850 --- /dev/null +++ b/doc/sphinx/.gitignore @@ -0,0 +1 @@ +_build diff --git a/doc/sphinx/Makefile b/doc/sphinx/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/doc/sphinx/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py new file mode 100644 index 00000000..4d46870d --- /dev/null +++ b/doc/sphinx/conf.py @@ -0,0 +1,43 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Phoebus' +copyright = '2024, Triad National Security' +author = 'The Phoebus Team' +release = '1.0.0' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ["sphinx_multiversion"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +# configuration for sphinx_multiversion +smv_remote_whitelist = r"^(origin)$" diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst new file mode 100644 index 00000000..d4550e87 --- /dev/null +++ b/doc/sphinx/index.rst @@ -0,0 +1,31 @@ +.. Phoebus documentation master file, created by + sphinx-quickstart on Thu Sep 26 15:18:20 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Phoebus: Performance portable GRRMHD for supernovae, mergers, and more +====================================================================== + +`Phoebus`_ is a performance portable general relativistic neutrino radiation magnetohydrodynamics code built upon the `Parthenon`_ adaptive mesh refinement framework. + +.. _Parthenon: https://github.com/parthenon-hpc-lab/parthenon +.. _Phoebus: https://github.com/lanl/phoebus + +Key Features +^^^^^^^^^^^^^ + +* Finite volume GRMHD +* Neutrino transport +* GR... +* fill out + +.. note:: + + These docs are under active development. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + :glob: + + src/* diff --git a/doc/sphinx/make.bat b/doc/sphinx/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/doc/sphinx/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/sphinx/src/code_of_conduct.rst b/doc/sphinx/src/code_of_conduct.rst new file mode 100644 index 00000000..1810e566 --- /dev/null +++ b/doc/sphinx/src/code_of_conduct.rst @@ -0,0 +1,76 @@ +Code of Conduct +===================================== + +The community of participants in open-source relativstic astrophysics +projects is made up of members from around the globe with a diverse set +of skills, personalities, and experiences. It is through these +differences that our community experiences success and continued growth. +We expect everyone in our community to follow these guidelines when +interacting with others both inside and outside of our community. Our +goal is to keep ours a positive, inclusive, successful, and growing +community. + +As members of the community, + +- We pledge to treat all people with respect and provide a harassment- + and bullying-free environment, regardless of sex, sexual orientation + and/or gender identity, disability, physical appearance, body size, + race, nationality, ethnicity, and religion. In particular, sexual + language and imagery, sexist, racist, or otherwise exclusionary jokes + are not appropriate. + +- We pledge to respect the work of others by recognizing + acknowledgment/citation requests of original authors. As authors, we + pledge to be explicit about how we want our own work to be cited or + acknowledged. + +- We pledge to welcome those interested in joining the community, and + realize that including people with a variety of opinions and + backgrounds will only serve to enrich our community. In particular, + discussions relating to pros/cons of various technologies, + programming languages, and so on are welcome, but these should be + done with respect, taking proactive measure to ensure that all + participants are heard and feel confident that they can freely + express their opinions. + +- We pledge to welcome questions and answer them respectfully, paying + particular attention to those new to the community. We pledge to + provide respectful criticisms and feedback in forums, especially in + discussion threads resulting from code contributions. + +- We pledge to be conscientious of the perceptions of the wider + community and to respond to criticism respectfully. We will strive to + model behaviors that encourage productive debate and disagreement, + both within our community and where we are criticized. We will treat + those outside our community with the same respect as people within + our community. + +- We pledge to help the entire community follow the code of conduct, + and to not remain silent when we see violations of the code of + conduct. We will take action when members of our community violate + this code such as contacting a Maintainer (a list of emails of + current Maintainers is made publicly available) or talking privately + with the person. + +This code of conduct applies to all community situations online (to +include Github Issues, Pull Requests and any communication therein as +well as Slack, Mattermost, and similar online communication platforms) +and offline, including mailing lists, forums, social media, conferences, +meetings, associated social events, and one-to-one interactions. + +Any related activity or project organized by members of the ``Phoebus`` +community, including affiliated packages, are welcome to have their own +codes of conduct, but agree to also abide by the present code of +conduct. + +-------------- + +This Community Code of Conduct was adapted from the `Astropy Community +Code of +Conduct `__ +available under a `Creative Commons Attribution 4.0 International +License `__. The above +Code of Conduct was modified for use as part of ``Phoebus``. + +Parts of this code of conduct have been adapted from the PSF code of +conduct. diff --git a/doc/sphinx/src/contributing.rst b/doc/sphinx/src/contributing.rst new file mode 100644 index 00000000..64db82f4 --- /dev/null +++ b/doc/sphinx/src/contributing.rst @@ -0,0 +1,88 @@ +Contributing +============================= + +For the purpose of our development model, we label *Contributors* or +*Maintainers* of ``Phoebus``. Below we describe these labels and the +process for contributing to ``Phoebus``. + +Becoming a Contributor +---------------------- + +We welcome contributions from scientists from a large variety of +relativistic astrophysics. New users are welcome to contributions to +``Phoebus`` via the *Contributors* process. Contributors with 6 merged +pull requests into the ``main`` branch (over a minimum of 6 months) will +be eligible to join as a *Maintainer* of ``Phoebus`` with additional +repository access and roles. However, final approval of *Maintainer* +status will require a unanimous approval by vote by existing +*Maintainers*, a necessary step to ensure the safety and integrity of +the code base for all users of ``Phoebus``. + +The *Maintainers* of ``Phoebus`` consist of the original developers of +the code and those that have a demonstrated history in the development +of ``Phoebus`` prior to the implementation of the *Development Model* +described here. Maintainers hold admin access, serve consistently as +reviewers for pull requests, and are in charge of the maintaining, +deployment, and improvement of efforts towards: regression testing, +documentation, science test cases (gold standards), and continuous +integration. + +To maintain their active status as Maintainer, all members will agree to +adhere to our Community Code of Conduct and sign a Memorandum of +Understanding described `here `__. + +Contributing to ``Phoebus`` +----------------------------- + +**Contributors**: (process for most users of ``Phoebus``) + +1. Create a new fork of ``main`` where your changes can be made. +2. After completing, create a pull request, describe the final approach + and ensure the branch has no conflicts with current Regression Tests + and Formatting Checks. +3. Assign external reviewers (a minimum of 1, one of which should be a + Maintainer, and which cannot be the contributor). Provide concise + description of changes. +4. Once comments/feedback is addressed, the PR will be merged into the + main branch and changes will be added to list of changes in the next + release. +5. At present, Releases (with a git version tag) for the ``main`` branch + of ``Phoebus`` will occur at a 6 to 12 month cadence or following + implementation of a major enhancement or capability to the code base. + +*Maintainers* of ``Phoebus`` will follow the same process for +contributions as above except for the following differences: they may +create branches directly within ``Phoebus``, they will hold repository +admin privileges, and actively participate in the technical review of +contributions to ``Phoebus``. + +List of Current Maintainers of ``Phoebus`` +------------------------------------------ + ++-------------------+--------------------------------+-----------------------+ +| Name | Handle | Team | ++===================+================================+=======================+ +| Brandon Barker | | Los Alamos National | +| | `@AstroBarker `__ | | ++-------------------+--------------------------------+-----------------------+ +| Josh Dolence | `@jdolence `__ | Lab | ++-------------------+--------------------------------+-----------------------+ +| Carl Fields | | University of Arizona | +| | `@carlnotsagan `__ | | ++-------------------+--------------------------------+-----------------------+ +| Mariam | `@mari2895 `__ | | ++-------------------+--------------------------------+-----------------------+ +| Jonah Miller | `@Yurlungur `__ | Lab | ++-------------------+--------------------------------+-----------------------+ +| Jeremiah Murphy | | Florida State | +| | `@curiousmiah `__ | | ++-------------------+--------------------------------+-----------------------+ +| Ben Ryan | `@brryan `__ | Lab | ++-------------------+--------------------------------+-----------------------+ diff --git a/doc/sphinx/src/governance.rst b/doc/sphinx/src/governance.rst new file mode 100644 index 00000000..4abc519a --- /dev/null +++ b/doc/sphinx/src/governance.rst @@ -0,0 +1,137 @@ +Organizational Structure +========================== + +| ``Phoebus`` uses a *hybrid flat-and-hierarchical* organizational + structure. +| The flat structure fosters power sharing among senior and junior + members and avoids the many pitfalls of power-over dynamics. For + example, in power-over structures, someone with explicit power can + inadvertently, or on rare occasions intentionally, silence critical + voices. +| This dynamic can quickly lead to an organization overlooking inherent + problems that could lead to ineffectiveness or even catastrophic + failure of the team. + +| In contrast, our aim is to illuminate potential problems early and + quickly find solutions. +| This strategy also efficiently taps into the diverse wealth of + knowledge of the team. +| At the same time, the PI and Co-PI have financial and reporting + responsibilities to their respective universities and funding + agencies. +| The general procedure for the hybrid structure is as follows. +| The flat structure will make major decisions in direction and + resources, and the PI and Co-PI will assume the responsibility for + executing those decisions. +| The following gives details on this hybrid structure. + +Team +---- + +The founding team consists of the following: original core developers +and Maintainers at Los Alamos National Lab, Jeremiah Murphy at Florida +State University, and Carl Fields at University of Arizona. + +Since, an objective of Phoebus is to grow the developer and user base, +the Phoebus Project will have an explicit mechanism for adding new +members. There are three categories for ``Phoebus`` members: +maintainers, contributors, and users. + +**User**: As open-source software, anyone may download, compile, and +execute ``Phoebus``. New users will encouraged to join communication +channels for connection with the larger ``Phoebus`` community. + +**Contributor**: Users who wish to contribute to ``Phoebus`` may do so +following our Development Model for new users. These changes will be +integrated into the main branch of the code upon approval. Consistent +contributions also provides the opportunity for Contributors to be +eligible to join as a *Maintainer*, the final approval of which will +require a vote. + +**Maintainer**: These are the core team who have “merge” permissions on +the repo and are working to keep the code sustainable long term. + +To maintain their active status as a User, Contributor, or Maintainer, +all members will agree to adhere to a Code of Conduct. + +Memorandum of Understanding +--------------------------- + +In addition to our Community Code of Conduct, all code Maintainers will +sign a memorandum of understanding (MoU) that will describe general +expectations and responsibilities. The MoU that will serve as part of +the ``Phoebus`` Community requires the following: + +- Maintainers will uphold and exemplify the *Development Model* + outlined as part of the ``phoebus`` Community described + `here `__. +- Maintainers will make a good-faith effort to attend team meetings. In + an effort to accommodate the dynamic schedules and availability of + many of the core team of *Maintainers*, coordination efforts will be + made to ensure that *at least* 1 *Maintainer* is present for all + meetings. +- Maintainers will make a good-faith effort to attend the annual + workshop. +- Maintainers will make a good-faith effort to monitor the fraction of + the meeting time that they speak. The meeting time is limited, and + several people may have something interesting to say, report on their + updates, or contribute constructive arguments. One should be + self-aware and notice if one is dominating conversations, and attempt + to make a conscious effort to include other voices and perspectives + in the discussion. +- Maintainers consider it their responsibility to voice their questions + and/or concerns as early as possible. This will ensure that the + organization addresses concerns rapidly and effectively. +- Maintainers consider it their responsibility to listen and understand + questions or concerns raised by other partners or through concerns + communicated through email to individual *Maintainers*. + +Approval by Vote: +----------------- + +| Many of the decisions in the organization will be enacted after an + approval by majority vote of the Maintainers. The process of listening + and adjusting strategies to meet everyone’s needs is vital for + power-sharing organizations. +| Importantly, spending a little time up front to listen and resolve + concerns reduces the pain and time spent later in intense conflict + resolution. + +Communication and Connection: +----------------------------- + +| To facilitate open and effective communication, the ``Phoebus`` will + offer multiple levels of communication. +| Developers will communicate via email, GitHub, and a ``Phoebus`` Slack + channel. + +| To respond to user inquiries, the Phoebus Project will host a mailing + list via Google or similar. +| To maintain a standing record of user inquiries and responses, we will + post the inquiries and responses on a public-facing site. +| All Maintainers will have the option to respond to the inquires; to + ensure that someone is responsive to the user inquiries, the team will + triage tickets/questions in a regular developer call. + +| Monthly Maintainer meetings will also be an important part of ensuring + productivity and timeliness of the meeting. +| Each meeting will last up to 60 minutes. We will assess and discuss + the goals from the previous meeting. +| In particular, we will take note which goals were completed and which + were not. If there are uncompleted goals, we will assess why they were + not completed. Next, we will discuss the goals for the upcoming month, + quarter, and year. +| We will decide which goals to move forward during the next month. +| All of this will be recorded on an online document which will be + available to all Maintainers. + +| Each meeting of the core Maintainers will be managed by a meeting + manager. +| The primary job of the meeting manager is to: 1) gather a list of + agenda items for the next meeting, 2) ensure that the meeting runs on + schedule, and 3) ensure equitable participation by all participants. +| Again, in keeping with power-sharing, the meeting manager position + will rotate among the core Maintainers, even junior members. We + maintain some flexibility in the cadence and structure of meetings, in + particular, in periods of low activity, meetings may be skipped or + held in a less formal manner. diff --git a/doc/sphinx/src/sphinx-doc.rst b/doc/sphinx/src/sphinx-doc.rst new file mode 100644 index 00000000..f24fb7a9 --- /dev/null +++ b/doc/sphinx/src/sphinx-doc.rst @@ -0,0 +1,134 @@ +.. _sphinx-doc: + +.. _Sphinx CheatSheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html + +How to Use Sphinx for Writing Docs +=================================== + +How to convert a Markdown file to rst +------------------------------------------ + +We are using the `reStructuredText`_ (rst) format for our documentation. +If you have a markdown file you would like to convert to rst, +as a first pass, you can have `Pandoc`_ convert your file. For example: + +.. code-block:: bash + + pandoc Metadata.md --from markdown --to rst -s -o metadata.rst + +Pandoc can be installed easily through a Linux package manager. For example on Ubuntu, + +.. code-block:: bash + + apt install pandoc + +will get you the tool. + +.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html + +.. _Pandoc: https://pandoc.org/ + +How to have github build your documentation for you +---------------------------------------------------- + +Github can automatically build your documentation for you through the continuous integration pipeline. +After you submit a pull request with your .rst changes for documentation on `github-pages`_, +the documentation will automatically get built. You will see a "build and deploy documentation" job +at the bottom of the pull request page. If this passes, your documentation will have been generated. + +On the bottom left of the documentation page on `github-pages`_, you can select the branch/build +of the documentation, one of which should be the branch you wrote your changes on. + +.. _github-pages: https://parthenon-hpc-lab.github.io/parthenon + + +Building documentation locally +------------------------------ + +While you can rely on the CI to build the documentation associated with your +branch, you can also very easily build sphinx documentation locally through +python. These instructions also *do not* require admin access and are usable +with shared machines or python distributions. + +First, ensure that you are running a modern version of python (i.e. python 3 of +some flavor) + +.. code-block:: bash + + $ python --version + Python 3.9.7 + +Then, use pip to install :code:`spinx` and the RTD theme + +.. code-block:: bash + + pip install --user sphinx sphinx-rtd-theme + +Now, navigate to the :code:`../doc/sphinx` directory where a :code:`make help` +shows all of the available ways to build the documentation + +.. code-block:: + + $ make help + Sphinx v4.2.0 + Please use `make target' where target is one of + html to make standalone HTML files + dirhtml to make HTML files named index.html in directories + singlehtml to make a single large HTML file + pickle to make pickle files + json to make JSON files + htmlhelp to make HTML files and an HTML help project + qthelp to make HTML files and a qthelp project + devhelp to make HTML files and a Devhelp project + epub to make an epub + latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + latexpdf to make LaTeX and PDF files (default pdflatex) + latexpdfja to make LaTeX files and run them through platex/dvipdfmx + text to make text files + man to make manual pages + texinfo to make Texinfo files + info to make Texinfo files and run them through makeinfo + gettext to make PO message catalogs + changes to make an overview of all changed/added/deprecated items + xml to make Docutils-native XML files + pseudoxml to make pseudoxml-XML files for display purposes + linkcheck to check all external links for integrity + doctest to run all doctests embedded in the documentation (if enabled) + coverage to run coverage check of the documentation (if enabled) + clean to remove everything in the build directory + +Making the documentation will create a new directory, :code:`_build` in the +:code:`sphinx` directory along with whichever type of documentation you wanted +to build. + +For example, building the HTML documentation with :code:`make html` produces the +:code:`../doc/sphinx/_build/html` directory with an :code:`index.html` file that +you can point a browser to in order to view the documenation. + + +How to Get the Dependencies +--------------------------- + +Using Docker +^^^^^^^^^^^^ + +If you are using `Docker`_, then simply pull the docker image specified below: + +.. _Docker: https://www.docker.com + +.. code-block:: + + image: sphinxdoc/sphinx-latexpdf + +Then, after running :code:`docker run -it /bin/bash`, install the theme we are using with :code:`pip install sphinx_rtd_theme` + +More Info. +---------- + +* `Sphinx Installation`_ + +.. _Sphinx Installation: https://www.sphinx-doc.org/en/master/usage/installation.html + +* `Sphinx reStructuredText Documentation`_ + +.. _Sphinx reStructuredText Documentation: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html