Comments (22)
AST parsing would add a bit of complexity, and would have to be in own module. Must agree on interface to the parser - but otherwise sounds like an improvement.
For instance one advantage could be, is that you choose to hide the doc.* code.
Like an option to exclude the code associated with doc.add_*()
calls from a handout? Could be neat!
from handout.
I'm using single line triple quotes for Markdown regularly.
from handout.
@danijar would you be open to a PR that uses the Python AST. Looking at this request and others, it might be worth to consider making the change to AST parsing, sooner rather then later. For instance one advantage could be, is that you choose to hide the doc.*
code.
from handout.
Tried # handout: exclude
right after the closing triple-quote in docstring in example.py (hoping it would get docstring excluded from html), but html did not work out as intended.
"""
# Python Handout
Turn Python scripts into handouts with Markdown comments and inline figures. An
alternative to Jupyter notebooks without hidden state that supports any text
editor.
""" # handout: exclude
Keeping docstring intact may be something users can expect, see here: #12 (comment)
from handout.
This feature would be useful in cases where I am producing a document with the help of results produced by my script and am not interested in showing any code.
from handout.
Thanks for bringing this up. It means both code and comments but not media inside a range exclude should be hidden.
You're example will be possible via range exclude. The # handout: exclude
operates on the current line only.
However, I don't think it'll be common to exclude docstrings. More likely, users would like to have them show in the code cell rather than a Markdown cell. I've opened #23 for that.
from handout.
I suggest that # handout: exclude
should operate on the current statement, so if that statement has multiple lines, exclude them all. It would make putting it after triple quotes work naturally. It would also allow conveniently excluding blocks such as for loops or normal statements spread out over many lines such as function calls with many parameters.
from handout.
Hi @alexmojaki, thanks for your suggestion. However, extracting statements would be both a big effort and likely to be brittle. Having # handout: exclude
hide the line its on and # handout: begin-exclude
and # handout: end-exclude
hide ranges has simple and clear semantics.
from handout.
No, it's pretty easy to implement robustly by parsing the AST. I'll do it myself if you're happy with the feature. It'd solve #23 / #15 and would generally fit people's expectations better, i.e. they don't try to hide a statement and hide only part of it instead.
from handout.
Excluding a statement, as @alexmojaki suggests, is indeed useful. The analogy that comes to mind is test coverage exclusion with #pragma: no cover
on coverage.py:
class MyObject(object):
def __init__(self):
blah1()
blah2()
def __repr__(self): # pragma: no cover
return "<MyObject>"
# handout: begin-exclude
and # handout: end-exclude
have their own uses too, but for example putting them around triple quoted string, especially the module docstring, is not desirable, I think.
from handout.
Hi @alexmojaki and @epogrebnyak, I have a hard time seeing how the benefit of one comment line instead of two outweighs the added complexity of parsing the input file's AST. Even though the behavior we could get from looking at the AST would be deterministic, it may still be hard to predict for users.
I'd be happy to accept a PR to support the syntax in the first post though. Otherwise, it's also one of the next things I'd be looking into adding.
from handout.
@danijar you're right, I thought it would be fun and got a bit carried away. I think it would be valuable to add eventually but shouldn't be a priority. Let me know if you'd like me to implement it in the future, e.g. if users ask for it.
from handout.
@alexmojaki Sounds good, thanks!
from handout.
Just as a reminder for code-parsing: I think we should check a single-line triplequoted string. I think It would be taken for code now, unless offset by whitespace.
from handout.
Thinking of edge cases for script text parsing:
"""one-line docsting"""
def foo():
"""docsting with offset"""
pass
doc = Handout('.')
doc.add_text('abc'); doc.add_text('zzz')
doc.html('<pre>foo</pre>')
# some code comment here
"""
Multiline
triple quoted
string
"""
print(True) #handout:exclude
Considerations:
- docstring may be one line
- allow whitespace in handout pragma
- several add_x() call per line
- cautiously purging empty lines
- concat of similar blocks (always or preserving user calls)
- comment with
#
is code
from handout.
The trailing # handout: exclude
for docstring seems possible without AST parsing:
"""
This docstring will be excluded
""" # handout: exclude
This can be useful to exclude module docstrings.
from handout.
A test input for block exclude:
# comment
# handout: begin-exclude
import sys;
sys.path.append('..')
# handout: end-exclude
print()
Should be parsed same as:
# comment
print()
Maybe there are some border cases?
from handout.
We mostly have to make sure to continue appending to the same code cell once the exclude range ends. The code should already be set up for this. Let's not change the behavior of single line excludes in the same PR.
By the way, triple quoted strings that start at the beginning of the line are considered Markdown. This is also true for single line comments. Docstrings are considered code since they are indented. I think module-level docstrings are not a big concern for now.
from handout.
Single line code comments are converted to markdown? I thought they stay as code. Need to run a conversion for myself to see how it works currently.
from handout.
Would a call to doc.add_something be processed inside a block exclude?
from handout.
Yeah, it would be nice to automatically exclude all handout related code since its generally not relevant how the document was generated unless otherwise specified.
from handout.
@eiso, thanks for the suggestion. I've opened #34 to discuss switching to the AST module.
from handout.
Related Issues (20)
- Opt-out of Markdown rendering for some multi-line comments HOT 2
- Support interactive environment in PyCharm where there is no source file HOT 6
- Comparison to Jupyter notebooks HOT 5
- Add contributing instructions HOT 1
- Pandas Dataframe Display Support HOT 4
- Making handout work with Jupyter HOT 3
- Convert jupyter notebook to handout HOT 5
- Use AST module to parse script rather than processing text line by line HOT 7
- Insert page breaks for print layout
- Generate handout every time the Python script is saved HOT 5
- Pathlib error when running setup.py on Linux HOT 8
- steps for porting to Julia HOT 6
- conda package HOT 3
- Possible to hide some code? HOT 1
- doc.show() will execute _generate method and rewrites index.html? HOT 1
- Add collapsible sections
- How to change the HTML page width? HOT 1
- image misplaced to end of file HOT 2
- Atom / VS Code / Sublime Text Extension HOT 1
- Need to install dependencies separately HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from handout.