Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
materialsproject committed Mar 26, 2024
1 parent 7394a39 commit ea05919
Show file tree
Hide file tree
Showing 42 changed files with 2,107 additions and 1,960 deletions.
14 changes: 10 additions & 4 deletions docs/_sources/installation.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@
Installing matminer
===================

Matminer requires Python 3.6+.
Matminer requires Python 3.9+.

It is strongly recommend that you install it in a virtual environment (using e.g., conda, Python's venv, or related tools) to avoid conflicts with other packages.

There are a couple of quick and easy ways to install matminer (see also some **tips** below):

Expand All @@ -28,6 +30,9 @@ or, to install matminer in your user home folder, run the command:
To update matminer, simply type ``pip install --upgrade matminer``.

This will install the latest version of all of matminer's dependencies.
In cases of future incompatibility, you can install the specific versions used for testing matminer by following the development instructions below.

Install in development mode
-----------------------------

Expand All @@ -42,15 +47,16 @@ and then enter the cloned repository/folder to install in developer mode:
.. code-block:: bash
$ cd matminer
$ python setup.py develop
$ pip install -r requirements/requirements-ubuntu_py3.11.txt # or corresponding file for your platform
$ pip install -e .
To update matminer, enter your cloned folder and type ``git pull`` followed by ``python setup.py develop``.
To update matminer, simply enter your cloned folder and type ``git pull``g
Tips
----
* Make sure you are using Python 3.6 or higher
* Make sure you are using a compatible Python version (3.9+ at time of writing).
* If you have trouble with the installation of a component library (sympy, pymatgen, mdf-forge, etc.), you can try to run ``pip install <<component>>`` or (if you are using `Anaconda <https://www.anaconda.com/distribution/>`_) ``conda install <<component>>`` first, and then re-try the installation.

- For example, installing pymatgen on a Windows platform is easiest with Anaconda via ``conda install -c conda-forge pymatgen``.
Expand Down
27 changes: 26 additions & 1 deletion docs/_static/basic.css
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down Expand Up @@ -237,6 +237,10 @@ a.headerlink {
visibility: hidden;
}

a:visited {
color: #551A8B;
}

h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
Expand Down Expand Up @@ -324,13 +328,15 @@ aside.sidebar {
p.sidebar-title {
font-weight: bold;
}

nav.contents,
aside.topic,
div.admonition, div.topic, blockquote {
clear: left;
}

/* -- topics ---------------------------------------------------------------- */

nav.contents,
aside.topic,
div.topic {
Expand Down Expand Up @@ -606,6 +612,7 @@ ol.simple p,
ul.simple p {
margin-bottom: 0;
}

aside.footnote > span,
div.citation > span {
float: left;
Expand Down Expand Up @@ -667,6 +674,16 @@ dd {
margin-left: 30px;
}

.sig dd {
margin-top: 0px;
margin-bottom: 0px;
}

.sig dl {
margin-top: 0px;
margin-bottom: 0px;
}

dl > dd:last-child,
dl > dd:last-child > :last-child {
margin-bottom: 0;
Expand Down Expand Up @@ -735,6 +752,14 @@ abbr, acronym {
cursor: help;
}

.translated {
background-color: rgba(207, 255, 207, 0.2)
}

.untranslated {
background-color: rgba(255, 207, 207, 0.2)
}

/* -- code displays --------------------------------------------------------- */

pre {
Expand Down
2 changes: 1 addition & 1 deletion docs/_static/doctools.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*
* Base JavaScript utilities for all Sphinx HTML documentation.
*
* :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down
5 changes: 2 additions & 3 deletions docs/_static/documentation_options.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
var DOCUMENTATION_OPTIONS = {
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
VERSION: '0.9.0',
const DOCUMENTATION_OPTIONS = {
VERSION: '0.9.1',
LANGUAGE: 'en',
COLLAPSE_INDEX: false,
BUILDER: 'html',
Expand Down
2 changes: 1 addition & 1 deletion docs/_static/language_data.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
* This script contains the language-specific data used by searchtools.js,
* namely the list of stopwords, stemmer, scorer and splitter.
*
* :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down
1 change: 1 addition & 0 deletions docs/_static/pygments.css
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ span.linenos.special { color: #000000; background-color: #ffffc0; padding-left:
.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
Expand Down
28 changes: 18 additions & 10 deletions docs/_static/searchtools.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*
* Sphinx JavaScript utilities for the full-text search.
*
* :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
Expand Down Expand Up @@ -57,12 +57,12 @@ const _removeChildren = (element) => {
const _escapeRegExp = (string) =>
string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string

const _displayItem = (item, searchTerms) => {
const _displayItem = (item, searchTerms, highlightTerms) => {
const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
const docUrlRoot = DOCUMENTATION_OPTIONS.URL_ROOT;
const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
const contentRoot = document.documentElement.dataset.content_root;

const [docName, title, anchor, descr, score, _filename] = item;

Expand All @@ -75,20 +75,24 @@ const _displayItem = (item, searchTerms) => {
if (dirname.match(/\/index\/$/))
dirname = dirname.substring(0, dirname.length - 6);
else if (dirname === "index/") dirname = "";
requestUrl = docUrlRoot + dirname;
requestUrl = contentRoot + dirname;
linkUrl = requestUrl;
} else {
// normal html builders
requestUrl = docUrlRoot + docName + docFileSuffix;
requestUrl = contentRoot + docName + docFileSuffix;
linkUrl = docName + docLinkSuffix;
}
let linkEl = listItem.appendChild(document.createElement("a"));
linkEl.href = linkUrl + anchor;
linkEl.dataset.score = score;
linkEl.innerHTML = title;
if (descr)
if (descr) {
listItem.appendChild(document.createElement("span")).innerHTML =
" (" + descr + ")";
// highlight search terms in the description
if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js
highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
}
else if (showSearchSummary)
fetch(requestUrl)
.then((responseData) => responseData.text())
Expand All @@ -97,6 +101,9 @@ const _displayItem = (item, searchTerms) => {
listItem.appendChild(
Search.makeSearchSummary(data, searchTerms)
);
// highlight search terms in the summary
if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js
highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
});
Search.output.appendChild(listItem);
};
Expand All @@ -115,14 +122,15 @@ const _finishSearch = (resultCount) => {
const _displayNextItem = (
results,
resultCount,
searchTerms
searchTerms,
highlightTerms,
) => {
// results left, load the summary and display it
// this is intended to be dynamic (don't sub resultsCount)
if (results.length) {
_displayItem(results.pop(), searchTerms);
_displayItem(results.pop(), searchTerms, highlightTerms);
setTimeout(
() => _displayNextItem(results, resultCount, searchTerms),
() => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
5
);
}
Expand Down Expand Up @@ -360,7 +368,7 @@ const Search = {
// console.info("search results:", Search.lastresults);

// print the results
_displayNextItem(results, results.length, searchTerms);
_displayNextItem(results, results.length, searchTerms, highlightTerms);
},

/**
Expand Down
16 changes: 13 additions & 3 deletions docs/_static/sphinx_highlight.js
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,19 @@ const _highlight = (node, addItems, text, className) => {
}

span.appendChild(document.createTextNode(val.substr(pos, text.length)));
const rest = document.createTextNode(val.substr(pos + text.length));
parent.insertBefore(
span,
parent.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
rest,
node.nextSibling
)
);
node.nodeValue = val.substr(0, pos);
/* There may be more occurrences of search term in this node. So call this
* function recursively on the remaining fragment.
*/
_highlight(rest, addItems, text, className);

if (isInSVG) {
const rect = document.createElementNS(
Expand Down Expand Up @@ -140,5 +145,10 @@ const SphinxHighlight = {
},
};

_ready(SphinxHighlight.highlightSearchWords);
_ready(SphinxHighlight.initEscapeListener);
_ready(() => {
/* Do not call highlightSearchWords() when we are on the search page.
* It will highlight words from the *previous* search query.
*/
if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords();
SphinxHighlight.initEscapeListener();
});
30 changes: 13 additions & 17 deletions docs/changelog.html
Original file line number Diff line number Diff line change
@@ -1,20 +1,16 @@

<!DOCTYPE html>

<html lang="en">
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

<title>MatMiner Changelog &#8212; matminer 0.9.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/nature.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<title>MatMiner Changelog &#8212; matminer 0.9.1 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/nature.css?v=8b5d5988" />
<script src="_static/documentation_options.js?v=9dc39874"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />

Expand All @@ -30,7 +26,7 @@ <h3>Navigation</h3>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">matminer 0.9.0 documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">matminer 0.9.1 documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">MatMiner Changelog</a></li>
</ul>
</div>
Expand All @@ -41,7 +37,7 @@ <h3>Navigation</h3>
<div class="body" role="main">

<section id="matminer-changelog">
<h1>matminer Changelog<a class="headerlink" href="#matminer-changelog" title="Permalink to this heading"></a></h1>
<h1>matminer Changelog<a class="headerlink" href="#matminer-changelog" title="Link to this heading"></a></h1>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>Starting v0.6.6 onwards, the changelog is no longer maintained. Please check the Github commit log for a record of changes.</p>
Expand Down Expand Up @@ -502,14 +498,14 @@ <h3>Navigation</h3>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">matminer 0.9.0 documentation</a> &#187;</li>
<li class="nav-item nav-item-0"><a href="index.html">matminer 0.9.1 documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">MatMiner Changelog</a></li>
</ul>
</div>

<div class="footer" role="contentinfo">
&#169; Copyright 2015, Anubhav Jain.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
&#169; Copyright 2015, Anubhav Jain.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
</div>

</body>
Expand Down
Loading

0 comments on commit ea05919

Please sign in to comment.