Add workflows to documentation #3043
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #3043 +/- ##
==========================================
- Coverage 69.46% 69.06% -0.40%
==========================================
Files 230 229 -1
Lines 16724 16752 +28
==========================================
- Hits 11617 11570 -47
- Misses 5107 5182 +75 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
*beep* *bop* Hi, human. The Click here to see your results. |
|
*beep* *bop* Significantly changed benchmarks: All benchmarks: Benchmarks that have stayed the same:
| Change | Before [99c9c8c5] <master> | After [2f6d4867] | Ratio | Benchmark (Parameter) |
|----------|------------------------------|---------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------|
| | 2.73±0.3μs | 3.57±0.5μs | ~1.31 | transport_montecarlo_vpacket.BenchmarkMontecarloMontecarloNumbaVpacket.time_trace_bad_vpacket |
| | 1.87±1μs | 2.26±2μs | ~1.21 | transport_montecarlo_estimators_radfield_estimator_calcs.BenchmarkMontecarloMontecarloNumbaPacket.time_update_line_estimators |
| | 41.0±20μs | 49.6±20μs | ~1.21 | transport_montecarlo_interaction.BenchmarkTransportMontecarloInteraction.time_line_emission |
| | 1.50±0.3μs | 1.75±0.3μs | ~1.17 | transport_geometry_calculate_distances.BenchmarkTransportGeometryCalculateDistances.time_calculate_distance_line |
| | 6.71±2μs | 7.63±2μs | ~1.14 | transport_montecarlo_vpacket.BenchmarkMontecarloMontecarloNumbaVpacket.time_trace_vpacket_volley |
| | 42.2±20μs | 46.4±30μs | ~1.10 | transport_montecarlo_interaction.BenchmarkTransportMontecarloInteraction.time_line_scatter |
| | 4.11±0.04ms | 3.72±0.04ms | ~0.91 | opacities_opacity_state.BenchmarkOpacitiesOpacityState.time_opacity_state_initialize('macroatom') |
| | 3.08±0ms | 2.73±0ms | ~0.89 | opacities_opacity_state.BenchmarkOpacitiesOpacityState.time_opacity_state_initialize('scatter') |
| | 20.8±5μs | 21.5±5μs | 1.04 | transport_montecarlo_packet_trackers.BenchmarkTransportMontecarloPacketTrackers.time_generate_rpacket_last_interaction_tracker_list |
| | 725±4ns | 740±0.7ns | 1.02 | transport_montecarlo_interaction.BenchmarkTransportMontecarloInteraction.time_thomson_scatter |
| | 2.55±0.5ms | 2.59±0.4ms | 1.02 | transport_montecarlo_single_packet_loop.BenchmarkTransportMontecarloSinglePacketLoop.time_single_packet_loop |
| | 1.65±0.01ms | 1.67±0ms | 1.01 | transport_montecarlo_main_loop.BenchmarkTransportMontecarloMontecarloMainLoop.time_montecarlo_main_loop |
| | 64.1±0.01ms | 64.7±0.1ms | 1.01 | transport_montecarlo_packet_trackers.BenchmarkTransportMontecarloPacketTrackers.time_rpacket_trackers_to_dataframe |
| | 591±200ns | 591±200ns | 1.00 | opacities_opacity.BenchmarkMontecarloMontecarloNumbaOpacities.time_pair_creation_opacity_calculation |
| | 20.9±0.05s | 20.8±0.01s | 1.00 | run_tardis.BenchmarkRunTardis.time_run_tardis |
| | 2.08±0m | 2.09±0m | 1.00 | spectrum_formal_integral.BenchmarkTransportMontecarloFormalIntegral.time_FormalIntegrator_functions |
| | 207±0.08ns | 206±0.07ns | 1.00 | spectrum_formal_integral.BenchmarkTransportMontecarloFormalIntegral.time_intensity_black_body |
| | 6.20±0.8μs | 6.19±0.9μs | 1.00 | transport_montecarlo_vpacket.BenchmarkMontecarloMontecarloNumbaVpacket.time_trace_vpacket |
| | 44.1±0.2s | 43.6±0s | 0.99 | run_tardis.BenchmarkRunTardis.time_run_tardis_rpacket_tracking |
| | 1.24±0μs | 1.23±0μs | 0.99 | transport_geometry_calculate_distances.BenchmarkTransportGeometryCalculateDistances.time_calculate_distance_boundary |
| | 38.1±0.09μs | 37.1±0.06μs | 0.97 | transport_montecarlo_packet_trackers.BenchmarkTransportMontecarloPacketTrackers.time_generate_rpacket_tracker_list |
| | 541±100ns | 521±100ns | 0.96 | opacities_opacity.BenchmarkMontecarloMontecarloNumbaOpacities.time_compton_opacity_calculation |
| | 3.40±0.8μs | 3.24±0.5μs | 0.95 | transport_montecarlo_vpacket.BenchmarkMontecarloMontecarloNumbaVpacket.time_trace_vpacket_within_shell |
| | 621±100ns | 581±200ns | 0.94 | opacities_opacity.BenchmarkMontecarloMontecarloNumbaOpacities.time_photoabsorption_opacity_calculation |
If you want to see the graph of the results, you can check it here |
|
Looking okay, the compiled notebooks in the docs are missing titles though (probably my fault :P ) |
|
I can add titles (once the v_inner notebook PR is merged so i don't edit over that one)! What exactly is the difference between the standard and simple workflows? |
Standard should provide all the logging output and plots e.g. convergence plots. Simple is just the raw text logs. |
There was a problem hiding this comment.
Pull Request Overview
This PR adds functionality to generate documentation pages for workflows by compiling all relevant notebooks into a new rst file and integrating the resulting page into the documentation structure.
- Added a new function in conf.py to generate a workflows page.
- Updated the application setup to include the newly generated workflows documentation.
Files not reviewed (1)
- docs/index.rst: Language not supported
Comments suppressed due to low confidence (1)
docs/conf.py:385
- The function name 'generate_worflows_page' appears to have a typo; consider renaming it to 'generate_workflows_page' for clarity.
def generate_worflows_page(app):
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
erinvisser
force-pushed
the
add-workflow-docs
branch
from
1095a42 to
18bf7bf
Compare
|
I think this would benefit from pre-running the notebooks. |
docs/conf.py
Outdated
| for root, dirs, fnames in os.walk("workflows/"): | ||
| for fname in fnames: | ||
| if 'workflow' in fname and fname.endswith(".ipynb") and "checkpoint" not in fname: | ||
| notebooks += f"\n* :doc:`{root}/{fname[:-6]}`" |
There was a problem hiding this comment.
I can see that this whole block of code is copied from existing things, so not necessarily your fault that the code is like this, but this entire logic block is a bit of nonsense that could be simplified heavily by using pathlib
Here's an example from stack overflow
from pathlib import Path
Path('my_file.mp3').suffix == '.mp3'
There are similar things to handle everything else that this is doing, like the .stem attribute
There was a problem hiding this comment.
You can try your hand at rewriting this logic with pathlib, or open an issue to keep note of it. Either is fine with me.
There was a problem hiding this comment.
I've been having trouble building the docs locally... do you think the following does the same thing? do you want something similar done to generate_tutorials_page and generate_how_to_guides_page as well?
notebooks = ""
workflows_path = Path("workflows")
for notebook in workflows_path.rglob("*.ipynb"):
if "workflow" in notebook.name and "checkpoint" not in notebook.name:
notebooks += f"\n* :doc:`{notebook.with_suffix('').as_posix()}`"
* added titles to workflow docs * created function to generate workflows.rst containing all notebooks in workflows folder * added workflows.rst to index.rst * called new function to actually generate workflows page * source code description * added description to workflows main page * added descriptions to individual workflow pages * rewrite logic w pathlib for generate_workflows_page
📝 Description
Type: 📝
documentationTo display the workflow docs on the documentation, I generated a new function in conf.py that compiles all notebooks within the workflows folder into a workflows.rst file. Then, I added that new section to index.rst, so it appears between How-To Guides and FAQs on the top section of the documentation.
☑️ Checklist
build_docslabel