Skip to content

Commit

Permalink
#95 final edits
Browse files Browse the repository at this point in the history
  • Loading branch information
@michaelweinold
michaelweinold committed Jul 29, 2023
1 parent c8f20ac commit 48bea3f
Show file tree
Hide file tree
Showing 3 changed files with 138 additions and 119 deletions.
29 changes: 23 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,14 +67,14 @@ You are now ready to build the documentation...

1. You can build the documentation by __triggering every build manually__: To trigger the build, run [`sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) from the repository root directory:

```
```bash
sphinx-build source _build/html -b singlehtml -a
```

| option | value | description |
| ---------------------------- | ----- | ----------- |
| sourcedir | `./source` | N/A |
| outdir | `./_build/html` | N/A |
| sourcedir | `source` | N/A |
| outdir | `_build/html` | N/A |
| -b | `singlehtml` | create only a single html page |
| -a | N/A | always write all output files |
| `-j` | `auto` | [speed up build by using multiple processes](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-j) |
Expand All @@ -88,14 +88,14 @@ _build/html/homepage.html

2. You can also build the documentation by automatically triggering a build after every change to the source files, providing a "live" preview of changes. To trigger the automated builds, run [`sphinx-autobuild`](https://github.com/executablebooks/sphinx-autobuild) from the repository root directory:

```
```bash
sphinx-autobuild source _build/html -a -j auto --open-browser
```

| positional argument or option| value | description |
| ---------------------------- | ----- | ----------- |
| sourcedir | `./source` | N/A |
| outdir | `./_build/html` | N/A |
| sourcedir | `source` | N/A |
| outdir | `_build/html` | N/A |
| `-a` | N/A | always write all output files |
| `-j` | `auto` | [speed up build by using multiple processes](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-j) |
| `--open-browser` | N/A | automatically open browser |
Expand All @@ -104,6 +104,23 @@ sphinx-autobuild source _build/html -a -j auto --open-browser
You can now preview the documentation at (the browser window will open automatically ✨):
http://127.0.0.1:8000/

### Checking for Dead External Links

The documentation contains links to external websites. To check if these links are still valid, run the following command from the repository root directory:

```bash
sphinx-build -b linkcheck -D linkcheck_workers=20 source _build/linkcheck
```

| positional argument or option| value | description |
| ---------------------------- | ----- | ----------- |
| `-b` | `linkcheck` | [`linkcheck` builder](https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder) |
| `-D` | `linkcheck_workers=20`` | [number of links to check in paralell](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_workers) |
| sourcedir | `source` | N/A |
| outdir | `_build/linkcheck` | `_build/linkcheck/output.txt` contains a list of all broken or redirected links |

Internal links, if formatted according to [the `myst-parser` cross-referencing specifications](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#cross-references), are checked automatically during the regular build process.

### Contributing

Please follow the extensive guide we have provided [on the documentation website](https://documentation.brightway.dev/en/latest/source/contributing/contributing.html).
Expand Down
224 changes: 115 additions & 109 deletions source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,17 @@
import datetime
import os

### project information ###########################################################################
###################################################################################################
### Project Information ###########################################################################
###################################################################################################

project = 'Brightway'
copyright = datetime.date.today().strftime("%Y") + ' Brightway Developers'
version: str = 'latest' # required by the version switcher

### project configuration #########################################################################
###################################################################################################
### Project Configuration #########################################################################
###################################################################################################

needs_sphinx = '7.0.1'

Expand Down Expand Up @@ -40,121 +44,21 @@
"sphinx_copybutton",
]

root_doc = 'index'
html_static_path = ['_static']
templates_path = ['_templates']
exclude_patterns = ['_build']
html_theme = "pydata_sphinx_theme"

# The root toctree document.
root_doc = 'index'

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

### suppress warnings ##############################################################################

suppress_warnings = [
"myst.header" # suppress warnings of the kind "WARNING: Non-consecutive header level increase; H1 to H3"
]

### extension configuration ########################################################################

## notfound configuration ################################################

notfound_context = {
'title': 'Page Not Found',
'body': '''
<h1>🍂 Page Not Found (404)</h1>
<p>
Oops! It looks like you've stumbled upon a page that's been recycled into the digital abyss.
But don't worry, we're all about sustainability here.
Why not take a moment to reduce, reuse, and recycle your clicks by heading back to the main page?
And remember, every little bit counts in the grand scheme of things.
</p>
''',
}

## autoapi configuration ################################################
## https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html#customisation-options

autoapi_options = [
'members',
'undoc-members',
'private-members',
'show-inheritance',
'show-module-summary',
#'special-members',
#'imported-members',
'show-inheritance-diagram'
]

autoapi_python_class_content = 'both'
autoapi_member_order = 'groupwise'
autoapi_root = 'api'
autoapi_keep_files = False

autoapi_dirs = [
'../brightway2-io/bw2io',
'../brightway2-data/bw2data',
'../brightway2-calc/bw2calc',
'../brightway2-analyzer/bw2analyzer'
]

autoapi_ignore = [
'*/data/*',
'*tests/*',
'*tests.py',
'*validation.py',
'*version.py',
'*.rst',
'*.yml',
'*.md',
'*.json',
'*.data'
]

## myst_parser configuration ############################################
## https://myst-parser.readthedocs.io/en/latest/configuration.html

source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown'
}

myst_enable_extensions = [
"amsmath",
"colon_fence",
"deflist",
"dollarmath",
"html_image",
]

## nbsphinx configuration ################################################

nbsphinx_execute = 'never'
nbsphinx_allow_errors = True

## sphinx-favicon configuration #########################################

favicons = [
{
"rel": "icon",
"sizes": "100x100",
"href": "logo/BW_favicon_100x100.png",
},
{
"rel": "apple-touch-icon",
"sizes": "500x500",
"href": "logo/BW_favicon_500x500.png"
},
]

## html configuration ###################################################
####################################################################################################
### Theme html Configuration #######################################################################
####################################################################################################

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
html_show_copyright = True

html_css_files = [
Expand All @@ -169,7 +73,6 @@
],
}

# https://pydata-sphinx-theme.readthedocs.io/en/stable/
html_theme_options = {
"announcement": "<p>Register Now: <a href='https://2023.brightcon.link/'>Brightcon 2023 Community Conference & Hackathon</a> 📍 Luxembourg 🗓️ 16.-20.September</p>",
# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html
Expand Down Expand Up @@ -221,9 +124,112 @@

# required by html_theme_options: "use_edit_page_button"
html_context = {
# "github_url": "https://github.com", # or your GitHub Enterprise site
"github_user": "brightway-lca",
"github_repo": "brightway-documentation",
"github_version": "main",
"doc_path": "source",
}
}

####################################################################################################
### Extension Configuration ########################################################################
####################################################################################################

# linkcheck Configuration ###############################################
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder

linkcheck_retries = 1
linkcheck_workers = 20
linkcheck_exclude_documents = []

# notfound Configuration ################################################
# https://sphinx-notfound-page.readthedocs.io

notfound_context = {
'title': 'Page Not Found',
'body': '''
<h1>🍂 Page Not Found (404)</h1>
<p>
Oops! It looks like you've stumbled upon a page that's been recycled into the digital abyss.
But don't worry, we're all about sustainability here.
Why not take a moment to reduce, reuse, and recycle your clicks by heading back to the main page?
And remember, every little bit counts in the grand scheme of things.
</p>
''',
}

# autoapi Configuration ################################################
# https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html#customisation-options

autoapi_dirs = [
'../brightway2-io/bw2io',
'../brightway2-data/bw2data',
'../brightway2-calc/bw2calc',
'../brightway2-analyzer/bw2analyzer'
]

autoapi_ignore = [
'*/data/*',
'*tests/*',
'*tests.py',
'*validation.py',
'*version.py',
'*.rst',
'*.yml',
'*.md',
'*.json',
'*.data'
]

autoapi_options = [
'members',
'undoc-members',
'private-members',
'show-inheritance',
'show-module-summary',
#'special-members',
#'imported-members',
'show-inheritance-diagram'
]

autoapi_python_class_content = 'both'
autoapi_member_order = 'groupwise'
autoapi_root = 'api'
autoapi_keep_files = False

# myst_parser Configuration ############################################
# https://myst-parser.readthedocs.io/en/latest/configuration.html

source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown'
}

myst_enable_extensions = [
"amsmath",
"colon_fence",
"deflist",
"dollarmath",
"html_image",
]

# nbsphinx configuration ################################################
# https://nbsphinx.readthedocs.io/en/0.9.2/

nbsphinx_execute = 'never'
nbsphinx_allow_errors = True

# sphinx-favicon configuration #########################################
# https://github.com/tcmetzger/sphinx-favicon

favicons = [
{
"rel": "icon",
"sizes": "100x100",
"href": "logo/BW_favicon_100x100.png",
},
{
"rel": "apple-touch-icon",
"sizes": "500x500",
"href": "logo/BW_favicon_500x500.png"
},
]
4 changes: 0 additions & 4 deletions source/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,10 +45,6 @@ Brightway is an open-source software package for [life cycle assessment](https:/

Brightway is designed to make it easy to work with large datasets and perform LCA calculations quickly and accurately. It thus provides a powerful tool for anyone interested in performing LCA or evaluating the environmental impacts of products and processes. Brightway is not intended to replace software like _SimaPro_ or _OpenLCA_, but instead offers possibilities to break the limits of conventional LCA. Brightway is especially attractive for researchers, especially when used with [Jupyter notebooks](https://jupyter.org/).

# Testing Dead Links

[This link works just fine.](https://www.srf.ch/news/schweiz/diebstaehle-in-zuerich-kriminelle-haben-es-auf-sonnenkollektoren-abgesehen) [But this link is broken!](https://www.srf.ch/news/schweiz/diebstaehle-in-zuerich--haben-es-auf-sonnenkollektoren-abgesehen)

```{toctree}
---
hidden:
Expand Down

0 comments on commit 48bea3f

Please sign in to comment.