Skip to content

Prepare template documents for furo style docs #1131

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 268 commits into from
Jun 3, 2025
Merged

Prepare template documents for furo style docs #1131

merged 268 commits into from
Jun 3, 2025

Conversation

fwitte
Copy link
Member

@fwitte fwitte commented Nov 8, 2024 •
edited by p-snft
Loading

Preview of the new docs: https://oemof-solph.readthedocs.io/en/docs-make-style-modern/index.html

Resolve #1074 (docs with appealing look)
Resolve #1132 (docs story line)
Resolve #1141 (beginner tutorials)

Note: #1142 (advanced tutorials) will be added later.

This PR prepares the change of the docs layout to the furo template. The following things have to considered before merging:

  • Check for compatibility of the old docs pages to the new template
  • Create darkmode replacements for every figure and logo
  • Insert darkmode/lightmode responsive figure inclusion code
  • Check if the docs actually build on readthedocs

On top of that, I updated the .readthedocs.yml configuration file to use the [dev] dependencies and a more up to date python version and delete the extra readthedocs specific requirements.txt file. It also introduces an announcement banner at the top of every page, where the content can be dynamically changed from the announcement.html file in the root of the announcements branch.

The plan is to crowdsource the necessary updates at the upcoming user-meeting.

@pep8speaks
Copy link

pep8speaks commented Nov 8, 2024 •
edited
Loading

Hello @fwitte! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

Line 130:80: E501 line too long (122 > 79 characters)

Comment last updated at 2025-01-16 07:00:41 UTC

@fwitte fwitte requested a review from p-snft November 8, 2024 15:59
@fwitte fwitte mentioned this pull request Nov 8, 2024
Open
@fwitte
Copy link
Member Author

fwitte commented Nov 8, 2024

I added instructions to contribute to this change for the in person meeting in the respective issue #1074

jfreissmann and others added 23 commits November 22, 2024 10:37
@jfreissmann
Add basic conecpt of flows file.
4f7ef57
@jfreissmann
Add basic conecpt of components file.
04b78a6
@jfreissmann
Add overview of basic concepts.
d312cca
@fwitte
Clean up some old files and update names
6c544c2
@fwitte
Make figure paths absolute
0025923
@maltefritz
Add showcase.rst
52aab71
@fwitte
Merge remote-tracking branch 'jfreissmann/docs/make-style-modern' int…
0a4fd2b 
…o docs/make-style-modern
@fwitte
Check in missing single file toc elements for new structure
a1f180a
@maltefritz
Add darkmode image of extraction turbine.
381f006
@maltefritz
Merge branch 'docs/make-style-modern' of github.com:oemof/oemof-solph…
e5afeef 
… into docs/make-style-modern
@paulapreuss
Add pages for introductory tutorials
f2d5c87
@paulapreuss
Add introductory tutorials overview page
021f9fb
@fwitte
Add a support template
1f1dfa5
@fwitte
Merge remote-tracking branch 'paula/docs/make-style-modern' into docs…
c11193a 
…/make-style-modern
@fwitte
Fix internal reference to building blocks
477ad5e
@fwitte
Merge remote-tracking branch 'mfritz/docs/make-style-modern' into doc…
e17605a 
…s/make-style-modern
@fwitte
Fix typo
1ddd75d
@pranaykasturi
Add structure for advanced tutorials in docs
f3218f0
@fwitte
Merge remote-tracking branch 'pranay/docs/make-style-modern' into doc…
e2f31ee 
…s/make-style-modern
@srhbrnds
Add oemof_solph_example_darkmode.svg to docs
bb03ce3
@fwitte
Make installation page look nice
f14e583
@fwitte
Fix typos
51cd2d6
@fwitte
Refactor the landing page to make it more compact for faster orientation
8fa7a62
@fwitte
Copy link
Member Author

fwitte commented Nov 24, 2024 •
edited by p-snft
Loading

@ALL: We need help with the following topics to get this out asap!

  • Is the proposed structure feasible? Are things missing or to be removed?
  • Is the new (shortened) landing page fine?
  • Are the installation information (those on the individual page) clear and do they actually work? What about HiGHS solver?
  • The tutorials need to be set up. We also need at least two advanced tutorials.
  • The showcase examples need to be filled.
  • We have to fix a date + time for the online support meetings Offering monthly consulation hours for users  #1136
  • We need to discuss how to split up the old usage section on the basic concepts and the advanced concepts sections.

@fwitte fwitte mentioned this pull request Nov 24, 2024
Open
@jfreissmann
Copy link

jfreissmann commented May 23, 2025 •
edited by fwitte
Loading

Open tasks (13.05.2025)

  • Check installation instructions @jfreissmann
  • Introductory tutorials
    • Rename section
    • Create Thumbnails
    • Remove Tutorial 4 (at least temporarily)
  • complete the tutorials @jfreissmann @maltefritz @p-snft @AntonellaGia
    • Finish the tutorial codes
    • Create icons for the grid view
    • Create plots and integrate them in the tutorial pages
  • Remove advanced tutorials for now
  • Showcases
    • Add showcase (SESMG, TUM Mobility App & MTRESS (@p-snft), OWP App)
    • Inquire other showcases from oemof devs/users
    • Reference oemof blog
  • Update the Support page @fwitte
  • Complete the figures for the grids in basic concepts and optimization sections
  • Include Buses and Flows into Energy System in "Basic Concepts"
  • Check text, references and links on all pages
  • Change "Best Practice" to "Recipe Book" and (later) gather those from oemof devs/users

p-snft and others added 8 commits May 23, 2025 17:44
@p-snft
Merge branch 'docs/make-style-modern' into docs/make-style-modern
c56c524
@p-snft
Merge pull request #1194 from maltefritz/docs/make-style-modern
69eac16 
Add introductory tutorial for district heating portfolio optimization
@p-snft
Fix missing references and includes
cf4f08e
@p-snft
Adhere to Black
398efb4
@fwitte
Fix a couple of broken references
5551102
@fwitte
Remove unused source file for advanced tutorials
75d6a53
@p-snft
Remove remains of advanced tutorials from docs
535f6d3 
The pages will be re-added once we have advanced tutorials.
@p-snft
Remove usage.rst
e4cc911 
The remaining contents seem to be irrelevant
or are handled somewhere else:
* usage -> Installation
* Warnings -> Should speak for themselves
* Result analysis -> Tutorials
* Groupings -> Hardly touched by users
* Excel reader -> oemof.tabular
@p-snft p-snft marked this pull request as ready for review June 3, 2025 09:27
@p-snft
Copy link
Member

p-snft commented Jun 3, 2025

I think we agreed to merge this and ask for additional feedback and showcase examples when this documentation is live in dev.

@jfreissmann
Copy link

jfreissmann commented Jun 3, 2025 •
edited
Loading

I verified the general installation via conda on MacOS as described in the Installation and setup setup and it worked fine.

On that occasion I noticed, that the supplied code snippets can cause unnecessary issue when directly coping the conde into a terminal:

conda create -n oemof-solph-env python=3.11
activate oemof-solph-env

I could not get this code snippet to work from copying the whole field with either pasting it in two lines or as one. I think it should be separated into two code fields in the documentation with the second line including the conda command.

@fwitte fwitte merged commit 1626491 into dev Jun 3, 2025
8 of 11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@p-snft p-snft p-snft left review comments

@oemof-developer oemof-developer Awaiting requested review from oemof-developer

Assignees

@fwitte fwitte

Labels
documentation enhancement
Projects
None yet
Milestone
No milestone