search

Klipper3d / klipper

Klipper is a 3d-printer firmware
GNU General Public License v3.0
9.39k stars 5.29k forks source link

example config cleanup #2205

Closed DMCShep closed 4 years ago

DMCShep commented 4 years ago

When viewing the example-extras.cfg file on mobile (a common thing when providing support on Discord), the example-extras.cfg page is often needed to be referenced. Due to the fact this has become the "catch-all", it is quite large in size, and in fact will freeze some mobile devices (including my LG G7 Thinq) when viewing. This makes it impossible to view on mobile devices, and once it manages to load, using the "find in page" can take minutes to look for occurrences.

Splitting this file up into manageable chunks would make a lot of sense. Just a quick example: example-stepper-drivers.cfg -- TMC settings for UART/SPI example-leveling.cfg -- for [z_tilt], [bed_tilt], probing, bed meshes, etc.

Additionally, as every new printer and mainboard gets supported, the list for these only becomes longer and the folder becomes daunting in size. Wondering if subfolders for "printers" and "boards" would make some sense instead of relying on prefixes to determine this, especially when the sample_macros.cfg gets shoved to the bottom where it is barely seen as a direct result.

klipper-gitissuebot commented 4 years ago

Hi @DMCShep,

It did not look like there was a Klipper log file attached to this ticket. The log file has been engineered to answer common questions the Klipper developers have about the software and its environment (software version, hardware type, configuration, event timing, and hundreds of other questions).

Unfortunately, too many people have opened tickets without providing the log. That consumes developer time; time that would be better spent enhancing the software. If this ticket references an event that has occurred while running the software then the Klipper log must be attached to this ticket. Otherwise, this ticket will be automatically closed in a few days.

For information on obtaining the Klipper log file see: https://github.com/KevinOConnor/klipper/blob/master/docs/Contact.md

The log can still be attached to this ticket - just add a comment and attach the log to that comment.

Best regards, ~ Your friendly GitIssueBot

PS: I'm just an automated script, not a human being.

BlackStump commented 4 years ago

@DMCShep something like this https://github.com/BlackStump/klipper/tree/config-reorganise/config

DMCShep commented 4 years ago

Wow! That is definitely a good start, your example-extras.cfg loads on my phone now and is snappy. Finding in page is still a bit slow, but way faster than original. So is clicking a line number -- now doable (something I forgot before was a bear) but still a bit slow. Highlighting text still drags however, I think there is definitely room for improvement still but it's a great start!

In your example-extras.cfg file, the last three lines mention replicape support and point to one of the moved files. Probably better to remove those three lines entirely as it is already stated to be in the relevant configuration file.

I do see that you named it example-extras-tmc-stepper-drivers.cfg -- this file is amazingly responsive and zero issues in any category. Wondering how it would perform if tmc was removed from the name and the Run-time stepper motor current configuration section (line 824 in example-extras.cfg ) were moved to example-extras-stepper-drivers.cfg?

Bed levelling file appears to be truncated at [skew_correction] -- not sure what happened there. Probe-bltouch looks great!

Wondering if -- due to the outstanding pull request for the LCD -- it might make a bit of sense to segregate out the display config to its own file too, knowing also that although at present time TFT is not supported, if (when?) it is added, it will have a natural home without growing the already-bloated file we are trying to fix.

Great work so far! I was going to see about doing something very similar but didn't get the chance before you beat me to the punch. Happy with what I am seeing!

BlackStump commented 4 years ago

@DMCShep I made the alterations, see what you think now.

https://github.com/KevinOConnor/klipper/blob/master/config/example-extras.cfg#L295 is that what you are seeing?

DMCShep commented 4 years ago

Yes, you are correct, and the replicape bit too.

The example-extras-stepper-driver.cfg file at 451 lines now seems to be right at the "comfort" limit, so I'd peg it at 500 lines max for good measure. This is a great reference point.

Trying to get closer to that point, the "customized homing" section is about 90 lines long, and the "fans" section is about 110 lines long. This would bring example-extras.cfg to 700 lines if those two were split out.

Macros is only 50 lines however seeing some issue tickets relating to them, it may expand, wouldn't be a bad idea to split those out. That would bring it down to about 650 lines total and should greatly help performance for me to re-test.

Thank you for this! It's coming along great right now!

JohnEdwa commented 4 years ago

Does viewing it "raw" as a text document help at all? It is just a long text document, only around 77.5KB in size, so nothing should have difficulties rendering that.

Sadly there doesn't seem to be a way to open it as a raw without actually first opening it as the page itself.

DMCShep commented 4 years ago

Sadly there doesn't seem to be a way to open it as a raw without actually first opening it as the page itself.

Unfortunately that is the entire problem, plus as we provide support on Discord one of the things we do is link to line numbers, which isn't possible in the raw view. The page does load fine in raw but that doesn't provide a complete solution.

BlackStump commented 4 years ago

@KevinOConnor Is this something you see some merit in? https://github.com/BlackStump/klipper/tree/config-reorganise/config

DMCShep commented 4 years ago

I don't think it's gonna get much better than this. Definitely about as good as I can get it, and mobile is usable on example-extras.cfg in every capacity now.

Also wondering Kevin's take on this, but your fork definitely addresses the issues I've been having in full.

KevinOConnor commented 4 years ago

I too find the example-extras.cfg file to be a bit unwieldy. However, I consistently get feedback that Klipper's documentation is a "bit scattered". That is, I've noticed a general theme of people voicing difficulty in finding the documentation they are looking for. In this regard, I've actually recently considered merging in portions of example.cfg into example-extras.cfg (and perhaps renaming to config-reference.cfg). I fear breaking the reference info multiple files could make it harder for people to find the info they are looking for - in particular a lot of modules don't easily fit in any one category.

So, my high-level feedback is that I'm not sure what the best option is. I don't think a change in the short term is likely. I'd like to continue to see what the feedback is.

FWIW, if rendering is an issue, we should be able to get the example configs up on klipper3d.org and it should be possible to implement some javascript to help annotate it. (For example, I wrote a small snippet of javascript to add a table of contents for the markdown files - the code is at the end of docs/_layouts/default.html .) If someone is interested in doing this, let me know.

-Kevin

DMCShep commented 4 years ago

Web developer of 6 years, sounds right up my alley! What did you have in mind that would need to be done?

DMCShep commented 4 years ago

Going to pitch a few ideas for klipper3d.org, will see if I can get a working prototype up on my own domain in the interim. I do not yet know of a decent way to keep a constant eye on example configs in a way that would list "unsorted" items, that would have to be manual in the interim... maybe a repo purely for configs where it can reference master at all times, kept in sync with the klipper repo so they are two distinct entities.

Tossing ideas out for now -- I do so much looking up of this type of thing for Discord support it's the bane of me to not know where to look or have a simple/intuitive way to find it, so this is a high priority for me to fix. I have a few things on my plate to address first, but once I do this will be next top item.

I think you may have hit the nail on the head -- things are scattered, but they are also super concentrated. So, allow people to choose what they prefer for a "best of both worlds" solution.

DMCShep commented 4 years ago

@KevinOConnor what web server are you using by the way for klipper3d.org? I'm currently running NGinx but am looking at allowing Apache to run alongside it, or even Node.js -- knowing what you use and aiming for the same thing should allow the easiest merging onto your site once it is up to your satisfaction.

mental405 commented 4 years ago

I think the "scattered" bit is that the processes and procedures for calibration and usage are in the MD docs and the config options are located in various configuration example files.

I don't think there is anything innately wrong with it, I just think that Klipper has outgrown it.

I agree that web documentation would be a good start. The config examples are all pretty well formatted so a parser should have no trouble picking out documentation comments from parameters, definitions, and fields. The fact that these files have a static URL means they can basically stay current with whatever is in the repo.

The Extras folder could be used as an index so each .py module gets a "section" in the documentation. Each section would reference the relevant [defintion] in the documentation and display it and its contents. The only major change to the current way of doing things would be to add a tag or tags in the .cfg files that points back to a relevant .md file if one exists.

KevinOConnor commented 4 years ago

what web server are you using by the way for klipper3d.org?

The klipper3d.org site is entirely run via "github pages". All the configuration for it is in the klipper repo (specifically docs/_config.yml and docs/_layouts/*).

I don't have an immediate vision for a web config viewing tool. However, I think a simple tool that added a table-of-contents for the config would be useful and hopefully it isn't too difficult. For reference, I wrote some javascript to add a table-of-contents to the generated markdown files on klipper3d.org (see the end of docs/_layouts/defaults.html).

-Kevin

Avalonnw commented 4 years ago

Not sure about config examples, but for actual config on my printer I've started using include statements in the main config and separate files for steppers, sensors, screen, menu, and so on. Helps a lot.

DMCShep commented 4 years ago

Not sure about config examples, but for actual config on my printer I've started using include statements in the main config and separate files for steppers, sensors, screen, menu, and so on. Helps a lot.

While not a bad idea, this issue ticket was made to try to better categorize the example configs for easy reference while helping others with their own config files. If entire portions of example configs are inaccessible due to the inability to load them adequately on a mobile phone, this is greatly hindered, and that is what is actively happening already. I see a lot of requests for how to properly set up TMC stepper drivers as a quick example and without being able to load the example-extras.cfg on mobile this makes pointing to the relevant place far more confusing for those we are helping.

DMCShep commented 4 years ago

Note for when I get a chance to work on this: focus on synonyms. Had a guy on Discord unable to find enclosure heater settings due to looking for the word "chamber", similar mix-ups have happened to myself also. Dictionary synonym searching can be done, but will be a later point.

Side note for those following: work will go in a separate repo and tracked there, this is more collective brainstorming and feedback gathering for now.

JeffDM2 commented 4 years ago

It would be nice to also have a g code macro in the example code for setting the enclosure temp.

iplop in the Klipper Discord posted this one today:

[gcode_macro M141 S{S}] gcode: SET_HEATER_TEMPERATURE HEATER=enclosure Target={S}

DMCShep commented 4 years ago

That reminds me to update the "to do" list!

I am still trying to decide between JavaScript and Python as a back end language, if I can use Python for back end but JavaScript for front end that would be ideal, I am still researching this. It's been a looooong while since I did Python and it was 2.x when I did so getting reacquainted is taking time.

darrellenns commented 4 years ago

Have you considered using sphinx (readthedocs.io)? I don't think it would take too much effort to rework the example configs and current markdown docs into a user guide.

KevinOConnor commented 4 years ago

I'm going to mark this as inactive as it doesn't look like it is currently being worked on.

-Kevin

ld3300 commented 4 years ago

Hi @KevinOConnor , Do you have any goals with the documentation that I can contribute to? Would a list at the top of example_extras and examples that identifies what is included in the document be helpful?

KevinOConnor commented 4 years ago

Alas, I don't have any great ideas on how to address this. It seems there are two competing concerns - we want the config section reference documentation all together so that people can easily find the full reference, but the size of that reference is causing some issues. I suspect an auto-generated index would be helpful (as in https://github.com/KevinOConnor/klipper/issues/2205#issuecomment-559291954 ), but it could be a bunch of work that may not end up being useful.

-Kevin

ld3300 commented 4 years ago

I spent a little time researching, and it looks like with some JavaScript and using the GitHub API we could auto generate a table of contents onto the docs webpage with linking to the associated code snippet for the example files. I just don't have the JavaScript know how to put the commands together.

KevinOConnor commented 4 years ago

Okay, I'm going to mark this as inactive again.

-Kevin

KevinOConnor commented 3 years ago

With the merge of #3545, the config reference has now been revamped.

-Kevin