Skip to content
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

WIP: include scripts in documentation instead of copy'n'paste #1558

Closed
wants to merge 1 commit into from
Closed

WIP: include scripts in documentation instead of copy'n'paste #1558

wants to merge 1 commit into from

Conversation

schmitts
Copy link
Contributor

No description provided.

@bcumming
Copy link
Member

I like it.
This means that we can test the code examples used in the documentation during CI, so that we don't have stale / out of date docs.
Does this require a specific version of Sphinx, or other dependencies?

@schmitts
Copy link
Contributor Author

Does this require a specific version of Sphinx, or other dependencies?

I see literalinclude mentioned at least back to 2010. I don't think it needs anything special.

@schmitts
Copy link
Contributor Author

What's the opinion on smaller code blocks, e.g., https://docs.arbor-sim.org/en/latest/python/profiler.html - these could also be moved to files and included. I'm in favour of doing so to have them CIable as @bcumming pointed out.

@brenthuisman
Copy link
Contributor

I'm a bit worried about line numbers going out of date. That's harder to spot than the code itself, at least for me. What do you think?

@schmitts
Copy link
Contributor Author

I'm a bit worried about line numbers going out of date. That's harder to spot than the code itself, at least for me. What do you think?

I agree. Maybe one should add a hint in the script like "This script is included in documentation. Adapt line numbers if touched.".

@schmitts schmitts marked this pull request as draft May 31, 2021 12:00
@noraabiakar noraabiakar self-assigned this Jun 1, 2021
@brenthuisman brenthuisman mentioned this pull request Jun 2, 2021
Merged
@brenthuisman
Copy link
Contributor

I'm incorporating this into #1575, because there I already needed to go through the tutorials.

brenthuisman added a commit that referenced this pull request Jul 27, 2021
@brenthuisman
Tutorial structure: remove deduplication, includify (#1575)
4543840 
* added notes re literal_include to python examples
* merged changes in #1504 
* deduped and includified (#1558) tutorials.
* First divergence of tutorial and code spotted!
* Added some contrib documentation for examples and docs.
max9901 added a commit to max9901/arbor that referenced this pull request Aug 5, 2021
@max9901 @thorstenhater
@brenthuisman @bcumming
fetch the upstream of mech abi implementation
19b7a77 
* Ci/sanitize (arbor-sim#1521)

Add clang sanitizer passes to GH CI.

* Tutorial structure: remove deduplication, includify (arbor-sim#1575)

* added notes re literal_include to python examples
* merged changes in arbor-sim#1504 
* deduped and includified (arbor-sim#1558) tutorials.
* First divergence of tutorial and code spotted!
* Added some contrib documentation for examples and docs.

* Implement mechanism ABI

Implements arbor-sim#1376.

* Provide a common C linkage ABI for externally compiled mechanisms, for both CPU and GPU.
* Remove mechanism type hierarchy (`concrete_mechanism` etc.), and move corresponding functionality to the back-end shared state objects. Mechanism catalogue is no longer indexed by type id.
* Distinguish between SIMD optimal alignment and SIMD width with new `min_align` attribute. Mechanisms provide both pieces of information via ABI.

* update spack package to include fmt for arbor@0.5.3: (arbor-sim#1609)

* alles werkt weer allen smol_dend niet;'

* nu werkt het

* Docs mechabi (arbor-sim#1610)

* Bit of review on the copy of the mech abi docs.
* Convert api/abi docs to C Domain directives.

* Bug/assorted static analysis (arbor-sim#1615)

* Fix failure to return value in `py_mech_cat_value_iterator `.
* String butchered by formatting.
* Join unnecessary separation of string literals in `arborio/cabelio.cpp`
* Add missing throw in s_expr code.
* Return value, not reference, in `merge_iterator::operator++(int)`.
* Check for self-assignment in `mechanism_catalogue`.
* Initialize all members of `mechanism`.
* Fix index check order in `multi_event_stream` debug output.
* Use coordinator_ from base class in `memory::array`.

Co-authored-by: thorstenhater <24411438+thorstenhater@users.noreply.github.com>
Co-authored-by: Brent Huisman <brenthuisman@users.noreply.github.com>
Co-authored-by: Ben Cumming <bcumming@cscs.ch>
max9901 added a commit to max9901/arbor that referenced this pull request Aug 9, 2021
@max9901 @thorstenhater
@brenthuisman @bcumming
Arbor sim master (#5)
8a7e3a9 
* Ci/sanitize (arbor-sim#1521)

Add clang sanitizer passes to GH CI.

* Tutorial structure: remove deduplication, includify (arbor-sim#1575)

* added notes re literal_include to python examples
* merged changes in arbor-sim#1504 
* deduped and includified (arbor-sim#1558) tutorials.
* First divergence of tutorial and code spotted!
* Added some contrib documentation for examples and docs.

* Implement mechanism ABI

Implements arbor-sim#1376.

* Provide a common C linkage ABI for externally compiled mechanisms, for both CPU and GPU.
* Remove mechanism type hierarchy (`concrete_mechanism` etc.), and move corresponding functionality to the back-end shared state objects. Mechanism catalogue is no longer indexed by type id.
* Distinguish between SIMD optimal alignment and SIMD width with new `min_align` attribute. Mechanisms provide both pieces of information via ABI.

* update spack package to include fmt for arbor@0.5.3: (arbor-sim#1609)

* Docs mechabi (arbor-sim#1610)

* Bit of review on the copy of the mech abi docs.
* Convert api/abi docs to C Domain directives.

* Bug/assorted static analysis (arbor-sim#1615)

* Fix failure to return value in `py_mech_cat_value_iterator `.
* String butchered by formatting.
* Join unnecessary separation of string literals in `arborio/cabelio.cpp`
* Add missing throw in s_expr code.
* Return value, not reference, in `merge_iterator::operator++(int)`.
* Check for self-assignment in `mechanism_catalogue`.
* Initialize all members of `mechanism`.
* Fix index check order in `multi_event_stream` debug output.
* Use coordinator_ from base class in `memory::array`.

Co-authored-by: thorstenhater <24411438+thorstenhater@users.noreply.github.com>
Co-authored-by: Brent Huisman <brenthuisman@users.noreply.github.com>
Co-authored-by: Ben Cumming <bcumming@cscs.ch>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@noraabiakar noraabiakar Awaiting requested review from noraabiakar

@brenthuisman brenthuisman Awaiting requested review from brenthuisman

Assignees

@brenthuisman brenthuisman

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@schmitts @bcumming @brenthuisman @noraabiakar