Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Overhaul installation documentation #351

Merged
merged 65 commits into from Jun 6, 2021

Conversation

bocklund
Copy link
Collaborator

@bocklund bocklund commented Jun 5, 2021

This PR:

  • Adds a JS-driven configuration tool to the installation docs to help configure the installation steps.
    • This is where users can configure some basic system- and configuration-specific options to get the installation that's right for them.
    • Mainly, this resolves items 1, 2, 5, 6, and 7 in DOC: pycalphad installation documentation overhaul #320 because we are giving users options w.r.t. pip vs. conda, environments and Jupyter.
    • The idea of the tool is that the HTML file, installation_configurator.html is mostly static except and the configurations are automatically generated and hardcoded with the logic from installation_configurator_generator.py. The HTML block is copy-pasted into the HTML file.
  • Rewrites each tool sections to give an overview of the main installation highlights. Because of the configuration tool, we don't have to spend a lot of time explaining the nuances of every possible configuration and platform.
  • The text mentions that git and compilers are required and points to a tutorial for installing the ones needed for Windows, addressing items 3 and 4 of DOC: pycalphad installation documentation overhaul #320.
  • Adds requirements-dev.txt to give the build and development requirements beyond the runtime requirements. Used in the source installation steps.

Closes #320.

Credit to spaCy's excellent installation documentation for the inspiration on the configuration tool and layout of the installation documentation content.

@bocklund
Copy link
Collaborator Author

bocklund commented Jun 6, 2021

image

Responsive on an iPhone 5SE size screen

I also updated to Furo theme and removed the environment-dev.yml

@bocklund
Copy link
Collaborator Author

bocklund commented Jun 6, 2021

I fixed the docs builds in CI, so it's passing now. I used the same commands as the configuration tool says to, so we have some "rough" testing of that, at least. I had to add the -U upgrade flag to get setuptools to be upgraded correctly (consistent with what the spaCy docs do).

I also added the ability to upload documentation build artifacts to GitHub, so they can be downloaded the GitHub Actions interface, for example: here. You can simply unpack that at your local machine, enter the directory, and run python -m http.server to run the docs as-built 😄

Coverage uploads are still broken and that's why the tests are failing.

@bocklund bocklund added this to the 0.9 milestone Jun 6, 2021
@bocklund bocklund requested a review from richardotis June 6, 2021 02:51
@bocklund
Copy link
Collaborator Author

bocklund commented Jun 6, 2021

Dark mode with the Furo doesn't look that good with all our content yet and there's no way to hard-code only light mode or give users a toggle to switch between them yet. Not sure if that's a dealbreaker.

@bocklund bocklund merged commit 53a1842 into pycalphad:develop Jun 6, 2021
@bocklund bocklund deleted the installation-tool branch June 7, 2021 01:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

DOC: pycalphad installation documentation overhaul
2 participants