Development Meeting Minutes

[michaelweinold]

...go here:

[michaelweinold]

09/12/2022, Initial Planning Meeting

Participants: @michaelweinold, @cmutel, @tngTUDOR
Location: Zoom

Agenda

1. Progress Report (@michaelweinold)

See below

2. Outlook (@michaelweinold)

See below

3. Discussion: UpWork Hiring (@michaelweinold)

See below

4. Discussion: Community Engagement (@michaelweinold)

We have interest from multiple researchers who would like to contribute to the documentation. Most are not proficient programmers, but enthusiastic users of Brightway. How do we best enable them to contribute to the documentation?

5. AOB (Any Other Business)

Progress Report

• Milestone 0.1.0. (completed 04/12/2022)

Completion of most relevant issues related to the prototype. Includes pulling changelog files from different Brightway repositories and parsing Python docstrings from different Brightway repositories.

This includes improvements:

• Create Content Page: Changelog #13
• Convert current rst pages to md #29
• Ensure git submodules are up-to-date #20
• Create API Reference Subpage #14
• Complete readme.md with updated instructions #19

And bugfixes:

• Fix submodules integration with readthedocs.org #23

Outlook

• Milestone 0.2.0.

All-round improvement of the prototype. Includes fine-tuning submodules setup and fixing most of the current build issues related to AutoAPI. Includes a first draft of the final outline in accordance with BEP003.

This includes improvements:

• Update Content Page: Setup #17
• Update Content Page: Contributing #32
• Update Content Page: Introduction #33
• Update Content Page: Credits and License #34
• Add Content Page: brightway-shine #11
• Update Content Page: LCA #35

And bugfixes:

• Fix AutoAPI build issues #36

Action Items

The following issues are important, but isolated enough to be taken over by other contributors:

• Add Content Page: brightway-shine #11
• Update Content Page: LCA #35

Minutes

@tngTUDOR and @cmutel agree that the best way forward is to provide an outline of the documentation pages and then open a call for the community to contribute. @michaelweinold is to act as g̶r̶a̶n̶d̶ ̶c̶e̶n̶s̶o̶r̶ curator of these contributions.

@tngTUDOR cautions against the use of submodules unless the implications on both the local and the remote (=readthedocs.org) are fully understood and documented. For instance, if a change is made to a docstring in bw_calc, this change would be propagated to the readthedocs.org build by the dependabot only once every weekday, while it would be present locally already. It is agreed to proceed with the submodules setup for now, considering also the advantages related to JS dependencies of some Brighway packages.

[michaelweinold]

13/01/2023, Progress Meeting

Agenda

1. Progress Report (@michaelweinold)

See below

2. Outlook (@michaelweinold)

See below, also compare this discussion on the new documentation sitemap.

3. Discussion: UpWork Hiring (@michaelweinold)

See below

4. AOB (Any Other Business)

Progress Report

• Milestone 0.2.0

All-round improvement of the prototype. Includes fine-tuning submodules setup and fixing most of the current build issues related to AutoAPI. Includes a first draft of the final outline in accordance with BEP003.

this includes:

General Issues

• Rename all Brightway repository master branches main #24
• Embedd fonts in .svg logos to ensure correct platform-independent rendering logo#2
• Create shields.io badge for Brightway logo#4
• Create Documentation Outline #38

Content Pages: Draft Completed

These pages are now ready to receive contributions from the wider user base.

• Create Content Page: Gallery (sphinx-gallery) #45
• Update Content Page: FAQ #42
• Update Content Page: Homepage #39
• Update Content Page: LCA #35
• Create Content Page: Documentation ("Documentation for the Documentation") #40

Content Pages: Completed

These pages are now completed.

• Update Content Page: Credits and License #34
• Update Content Page: Setup #17
• Update Content Page: Contributing #32

Infrastructure

Related to input by @tngTUDOR:

• Set up sphinx-tabs within .md (myST) files #43
• Fool-proof submodules local/readthedocs.org integration #37

Outlook

1. UpWork hiring: to commence in mid-January
2. Fix AutoAPI build issues #36
3. Add new Brightway Documentation Page to pydata-sphinx Example Gallery #44

[michaelweinold]

Call to action sent out on 15-01-2023 to:

• Brightway Mailing List
• LCA Discussion List
• Brightcon 2022 Documentation Hackathon Participants (compare Improve Brightway Documentation hackathons#10)
• other interested parties

[michaelweinold]

03/03/2023 Progress Meeting

Agenda

1. Progress Report (@michaelweinold)

See below

2. Outlook (@michaelweinold)

See below

3. A round of applause 👏🏻 (@cmutel , @tngTUDOR)

4. Update: UpWork Hiring (@michaelweinold)

5. Tasks for @cmutel & @tngTUDOR:

• How to deal with bw2 vs bw2.5 in the documentation? Should 2.5 packages be published to conda-forge?
• Test the documentation.
• Sign off on the initial deliverables of the documentation.

6. AOB (Any Other Business)

Progress Report

Content Issues

• Update Content Page: Homepage #39 (add Diataxis information matrix)

Technical Infrastructure Issues

• Create Content Page: Gallery (sphinx-gallery) #45 (myst-nb does not allow to download runnable notebooks directly)
• Fool-proof submodules local/readthedocs.org integration #37 (implement, test and document GitHub actions)

API Documentation Issues

• Fix AutoAPI build issues #36
• API: Prepare Technical Documentation Requirements #50

Outlook

Remaining Low-Priority/Long-Term Issues

• Bump sphinx version to 6.x.x #51
• Test GPT Integration ("ask the docs") #48
• Create Discussion Templates for Documentation Feature Requests #46
• Add new Brightway Documentation Page to pydata-sphinx Example Gallery #44

Final Long-Term Issues

• Clean up Old Documentation Repositories/Pages #15

[michaelweinold]

03/04/2023 Progress Meeting

Agenda

1. Progress Report (@michaelweinold)

See below

2. Outlook (@michaelweinold)

readthedocs.org Community Gold Subscription (as per suggestion of @cmutel)
For other points, see below

5. AOB (Any Other Business)

Progress Report

Content Issues

• Add documentation/repos on docker images #65
• Clean up Old Documentation Repositories/Pages #15

Technical Infrastructure Issues

• Implement Unified Legacy Branch Naming across Brightway Packages #61
• Logo path broken (#1) #59
• Switch to Conda for readthedocs builds #6
• Inheritance Diagrams broken on readthedocs.org #68

API Documentation Issues

• API: Prepare Technical Documentation Requirements #50

Outlook

Remaining Low-Priority/Long-Term Issues

• Bump sphinx version to 6.x.x #51
• Test GPT Integration ("ask the docs") #48
• Create Discussion Templates for Documentation Feature Requests #46
• Add new Brightway Documentation Page to pydata-sphinx Example Gallery #44

[michaelweinold]

26/06/2023 Progress Meeting

Agenda

1. Progress Report (@michaelweinold)
2. Strategic Decisions (@michaelweinold)
   2.1. Inadequacy of the present API Documentation: The API Documentation is completely useless! 🫣😢 #83
3. Outlook (@michaelweinold)
4. AOB (Any Other Business)
   5.1. @cmutel: Update on readthedocs.org Community Gold Subscription ✅

Progress Report

Content Issues

• Add Diataxis Grid to the Sidebar #81
• Add Footer with "open an issue on GitHub" or similar #73
• Delete/Archive Repo homepage #79
• Improvement of SimaPro csv Export Documentation #90

Technical Infrastructure Issues

• Pin all Dependencies #70
• Use sphinx_favicon to replace deprecated 'favicon' option of pydata-sphinx-theme #72
• Fix .gitmodules Sync #71

API Documentation Issues

• Docstrings in __init__ of class does not render correctly in Sphinx #69

Outlook

Remaining Issues

High Priority

The sphinx build infrastructure needs to be upgraded. Currently, there are two separate blockers (one for the upgrade to sphinx 6, one for the upgrade to sphinx 7):

• Bump sphinx version to 6.x.x #51
• Bump sphinx version to 7.x.x #92

The pydata-sphinx-theme somehow has brought back an issue that breaks the logo path:

• Logo path broken (#1) #59

The infrastructure of the example gallery needs to be upgraded to accommodate new examples (from the Depart-de-Sentier Visualization Contest):

• Create Content Page: Gallery (sphinx-gallery) #45
• Create Example Gallery Repository #96

Other issues:

• Redirect/Point all non-legacy specific Pages to latest #74
• Check for Dead Links #95

Lower Priority

• Test GPT Integration ("ask the docs") #48
• Create Discussion Templates for Documentation Feature Requests #46
• Add new Brightway Documentation Page to pydata-sphinx Example Gallery #44

[michaelweinold]

06/12/2023 Handover Meeting

• Add Brightway to Featured Example Gallery Grid pydata/pydata-sphinx-theme#1580 (mic drop 🎤💥)