New Documentation

[jbrazio]

Continuing the discussion which went a bit off-topic at #3063.

Wikis are basically garbage, the effort required to make one look good and easy to navigate is not productive because in the end of the day users will not update them, they are over complicated. After been told by @thinkyhead what happened in the past and due to the good experience we have in overall with Github I decided to build a mock up based on Jekyll and Github Pages.

1. All documentation is stored on Github
2. The repository is property of the MarlinFirmware Github organization
3. Everyone can fork and contribute in a standard manner like they already do to Marlin and MarlinDev
4. We can use our own domains which means the previous idea can have continuity
5. Documentation can be build either in html or in markdown

The mock up I've build can be found at jbrazio/MarlinDocumentation and it can be live previewed here.

I'm demoing the following concepts:

1. Intro page with key Marlin features
2. Quick start guides - shall be guide a newb user from start to finish to have Marlin up and running
3. Documentation - Where the current "wiki" will go

Only three links works currently:

• "Learn more" which goes to a intro page
• "Rich G-Code Support > View details" which goes into the G-Code listing
• "Documentation" which generates a list of pages under the "docs" category

Please have a look and let's take this as a starting point to build something great.

[thinkyhead]

That looks great. Let's do this thing!

[jbrazio]

Great ! I'm proceeding with it.

[elijahsgh]

How do I contribute to this?
On a cursory look I only see a proof-of-concept link. Will there be a MarlinDocumentation repository?

[jbrazio]

I've been building a proof of concept which I believe it's now almost functional, the only missing piece for me is custom java script markdown tags so we can have consistent look on attention callouts and such.

If you want to help, you may fork my repo for now and start migrating the Marlin wiki-markup to markdown inside the articles folder.

We also need a README.md file explaining how to get started with Jekyll and well.. contributing. :-)
I hope to have most of this sorted out during the next weekend.

[jbrazio]

@thinkyhead It is also important that somehow we "block" pages that were already migrated otherwise It's hard to have both systems in sync. Does Github allow locking a specific wiki page ?

[elijahsgh]

Let's get this thing wired up proper so it can start receiving contributions. Marlin/MarlinDocumentation repo maybe soon?

Worrying about locking pages is just going to be a delay or cause a future delay.

[Blue-Marlin]

It's a wiki!
Joust add: "Don't change right now! Porting."
And when done. "Ported to [link]"

[elijahsgh]

Any update?

Marlinfirmware/MarlinDocumentation sounds like a decent place to spend a Sunday evening.

[jbrazio]

Why wait for Sunday ?.. Nothing stops you from forking my repo right now and start working on it. ;-)

[elijahsgh]

Get the official project space pushed forward to enable contributors to begin adding their value to the project in a meaningful capacity.

If you don't understand the risk and you do not value or respect your contributors enough to know why they may not want to fire contributions into a potential black hole upstream independent of the project........ I can't even finish this without twitching in pain.

Again, I've taken 15 steps forward here so meet me near-ish the middle, yea?

[jbrazio]

We have now a glorious README.md.

[elijahsgh]

👍

[jbrazio]

@thinkyhead @AnHardt @Roxy-3DPrintBoard who is controlling marlinfirmware.org ? It was renewed yesterday.

Updated Date: 2016-03-13T01:21:19Z
Creation Date: 2015-03-12T15:12:01Z
Registry Expiry Date: 2017-03-12T15:12:01Z

[AnHardt]

Yes. I also tried to grab it. I did not talk about that to avoid a race. But it was simply continued for an other year.
The owner was/is @scotty1024 (#1592 (comment) and following messages), but he does not respond since last summer.

If you are interested you can use 'Marlin-Firmware.org'.
Currently there are some redirections:
marlin-firmware.org -> http://github.com/MarlinFirmware/Marlin
*.marlin-firmware.org -> http://github.com/MarlinFirmware/Marlin
wiki.marlin-firmware.org -> http://github.com/MarlinFirmware/Marlin/wiki

If you want some other redirections - ask for it.
Even mail redirections are possible.
No web space, no databases, no pop or imap accounts - just redirections

Sorry. No other administrative account for you. (Otherwise you could change all my other domains.)

EDITED

[jbrazio]

Thanks ! No need for admin stuff, just set and forget a CNAME record. I'm in mobile right now, so will get back to you later on today if you don't mind.

[AnHardt]

The new docu is looking great to me.
There is just one point iritating me. The font. Numbers do look very uneven. "G92" is more looking like "Gg2"

[AnHardt]

@Roxy-3DPrintBoard
If we want it, i suppose, you (the owner) has to transfer the example repository to MarlinFirmware

[AnHardt]

Ahh, sorry, not exactly.
https://help.github.com/articles/transferring-a-repository/

[jbrazio]

Transferring from a user to an organization
Users must have admin or owner rights within the receiving organization before they can transfer a repository that they individually own. If the user does not already have this level of access, a temporary admin team can be created with only the user. The user sending the repository is the only one who can perform the transfer.

[Roxy-3D]

If we are ready to move it... Just tell me to do it. One thing not mentioned in this quote is another possibility:

Transferring from a user to an organization:
Users must have admin or owner rights within the receiving organization before they can transfer a repository that they individually own. If the user does not already have this level of access, a temporary admin team can be created with only the user. The user sending the repository is the only one who can perform the transfer.

We can create a temporary (never to be used again) user account that both the receiving side and the original side have admin rights to. Instead of doing the transfer in one step, we do it in two steps.

[jbrazio]

As last resort I believe it can be transferred to someone inside the org with enough rights (user to user) and then from that user account to org.

[Roxy-3D]

When there is consensus I'll do what ever it takes to make it happen. But you will probably have to give me 3 or 4 easy to understand steps that happen in order.

Just for my benefit, can we have a quick discussion about the merits of doing Push Requests on the documentation? If the documentation is it's own repository (within the MarlinFirmware organization) we should be able to give the Documentation team leaders authority to approve Push Requests against it. Does that handle everybody's concerns and needs?

[elijahsgh]

@Roxy-3DPrintBoard I thought we had consensus about 5 times over? Even @thinkyhead seemed to greenlight it above.

Step 1) Clone the repo.
Step 2) Create a new repository.
Step 3) Point the cloned repo to the repository upstream (follow the instructions github gives you and just edit .git/config and update the URLs)
Step 4) Push

The downside to the github wikis are that whole pages have to be edited. The upside to things like Jekyll is that we can manage it exactly like a git repository - merge, pull, clone, PR, etc.

Let's go!

[jbrazio]

@Roxy-3DPrintBoard This new documentation system is not a wiki, the concept is everyone can contribute but someone must curate it, in fact Travis is even doing validation if everything is being build as it supposed to be.

Then there are two steps, one is the process of including new contributions on the master branch; the second one is to rebase gh-pages from master which only then will introduce the changes live on the website.

@tamarintech what we had reached is that when we find it is ready it will be transferred up to then it stays where it is right now, the location of the $%&"! thing does not block anything.

[Roxy-3D]

I like the way the left hand topics list changes how it is high lighted as you scroll down the page. It would be really cool if the high lighted topic could automatically expand and show its bullet points indented underneath it.

This really does look pleasing and professional. Can we talk about how hard it is for a random person with no experience with these tools to go in and expand a topic area and have it pretty much work? Suppose in that screen shot up above I wanted to add some extra information or constraints to the Power Supply types. I want to add 3 = Fuel Cell. Am I going to be able to find that in the files easily? Can I make the changes without causing everything to break?

[jbrazio]

It's indeed doable, I'll try to hack something about it on Sunday.

If it is the first time you're contributing, and want to do it the right way, then you must do:

git clone <repo URL>
git checkout -b new-cool-stuff

[edit the file located in articles/]

git add -A
git commit -m "Edited the article ZXY"
git push

[do PR in Github]

(People can skip the branch stuff if they want to save some keystrokes)

This allows you not only to edit articles but add new site sections, edit existing templates, move stuff around, publish news etc etc.

[thinkyhead]

I generally support anything we can host in the repo. The domain issue is something to work out, and perhaps it is not so hard to keep a domain alive and well for a while.

easily fixable by transferring the ownership to the core team

Whoever that is, this week. And that's the main issue. Marlin really doesn't have a "core team."

But the owner of the MarlinFirmware org name on Github is Erik van der Zalm. He works at Ultimaker with David Braam, the original author of Cura. Parts of Marlin early on were authored by Bernard Kubicek. I suppose if anyone should be the key holder for an "official domain" it should be Erik, because anyone else may come and go.

Anyway, I'm looking forward to editing some documentation soon! But over the next 24 hours or so, I want to get all the pieces in place to release RC4, probably reverting #3082 until we have a stronger consensus how best to disable probes when not in use. Perhaps we'll have that figured out for the next (and final) release candidate, and maybe it will be more attuned to the approach taking shape in #3065.

[jbrazio]

That gave a clear view of the Marlin roots, but for now they seem to be a bit "offline" on the project; from an outsider as I am the current active maintainers are @Roxy-3DPrintBoard, @thinkyhead, @AnHardt and @Blue-Marlin.

I was following the RC4 build up and I must admit #3082 and all the config changes it introduces really went by me unnoticed but I do agree with the principle of simplifying the concept.

I have stopped converting the existing Wiki documents to the PoC system because it's a bit uncertain for me if it will be used and I don't want to create double work by having to revert all the wiki documents to their original state. If you have a look some are now marked as DNE (Do Not Edit).

PS: I'm still owning Roxy a pretty folding TOC.

[thinkyhead]

Now that our less-rickety Marlin 1.1.0-RC4 is out to the world, it seems like an opportune time to add to the documentation and get out another build of the "test" wiki in-progress.

Speaking of documentation… On Wednesday I will be doing an informal presentation on Marlin Firmware at the Portland 3D Printing Lab monthly meetup. My outline for the presentation goes sort of like this:

• Who am I? Why am I here? How did I fall in love with plastic-squirting robots?
• A basic overview of Marlin: What it is, its illustrious history, genealogy since grbl/sprinter
• The miraculous way that Marlin develops, the Github process, evolutionary development
• A short overview of Marlin configuration (in 1.1.0 – no 1.2 "exploded configurations")
• Along the way describe the many changes to Marlin since "Marlin 1.0"
• After that, the future of Marlin (always better)
• Invite involvement in the project, and the documentation project.
• Give links of where to go for more information (here and the RepRap Forums "Marlin" section)

If a video is made, that will be good. Otherwise, I can perhaps take my slides and add audio, and put that up on YouTube later.

[Roxy-3D]

If a video is made, that will be good. Otherwise, I can perhaps take my slides and add audio, and put that up on YouTube later.

It would be really good if your presentation can be recorded and posted!

[jbrazio]

For sure it would give a jump start to the Marlin Youtube channel :-P

[jbrazio]

@thinkyhead @Roxy-3DPrintBoard @AnHardt did you had time to discuss if we should proceed with my suggestion and the current PoC repo be migrated to MarlinFirmware/MarlinDocumentation thus using the domain marlinfw.org as the official "concentrator" website ?

[thinkyhead]

good if your presentation can be recorded

@Roxy-3DPrintBoard Hopefully good! I'm trying to narrow it down so it isn't too geeky.

discuss if we should proceed with my suggestion

@jbrazio I guess we should discuss that here. I have no objection to migrating it into a new project under MarlinFirmware. Seems like the right thing to do, and then keep going forward with it in tandem with the rest of the repos.

[Roxy-3D]

I think the idea of migrating all of the documentation to MarlinFirmware/MarlinDocumentation makes sense.

I need some help to understand how using the marlinfw.org as an "Official Concentrator" helps things. It would seem everything can be done within MarlinFirmware/MarlinDocumentation.

[thinkyhead]

There may be some other hosting options to consider… This one comes up near the top of my web searches: http://www.simplybuilt.com/explore/free-websites-for-open-source-projects

There may be other advice worth considering also.

[jbrazio]

There may be some other hosting options to consider

I guess we could do it.. but starting with Git pages will allow us to start lean, fast and scale out to another hosting platform when [and if] required.

I need some help to understand how using the marlinfw.org as an "Official Concentrator" helps things. It would seem everything can be done within MarlinFirmware/MarlinDocumentation.

You can access a Git hub page by two ways:

• the native URL which for the PoC is http://jbrazio.github.io/MarlinDocumentation
• a custom domain, which for the PoC is http://test.marlinfw.org

But both ways are served exactly from the same source repository.
@Roxy-3DPrintBoard this this answered your concerns or did I miss the point ?

[Roxy-3D]

But both ways are served exactly from the same source repository. @Roxy-3DPrintBoard this this answered your concerns or did I miss the point ?

I guess I misunderstood. I got confused and thought we were talking about an "Official Concentrator" web site that was not on GitHub as the only way to get to the documentation. It feels more natural to me that everything be on GitHub but that is based on what I know and understand right now.

Are we ready to create a 'Documentation' project within MarlinFirmware?

[jbrazio]

For me we can proceed, just tell me to whom I transfer the existing one for importing.

[Roxy-3D]

For me we can proceed, just tell me to whom I transfer the existing one for importing.

Are we ready to create a 'Documentation' project under MarlinFirmware? If we are ready to move content there, we just need agreement that makes sense to do.

[jbrazio]

I'm closing this issue as the new Documentation Project repository has been created.
Have a look at MarlinFirmware/MarlinDocumentation.

[fontanares]

Hello!
My english is poor and
I can hardly time to translate it . Can someone send me or tell me where to find the configuration manuel Marlin?
In particular I look for the parameters " EXTRUDER_RUNOUT " .
Thank you.

my mail is: [email protected]

[thinkyhead]

We don't have a manual yet. Here's what I can tell you. First, the configuration file gives a reasonable explanation…

//  extruder run-out prevention.
//if the machine is idle, and the temperature over MINTEMP, every couple of SECONDS some filament is extruded
//#define EXTRUDER_RUNOUT_PREVENT
#define EXTRUDER_RUNOUT_MINTEMP 190
#define EXTRUDER_RUNOUT_SECONDS 30
#define EXTRUDER_RUNOUT_ESTEPS 14   // mm filament
#define EXTRUDER_RUNOUT_SPEED 1500  // extrusion speed
#define EXTRUDER_RUNOUT_EXTRUDE 100

Note that the comment on EXTRUDER_RUNOUT_ESTEPS is nonsense. It does not specify millimeters.

Here's what the code is actually doing with these values…

planner.buffer_line(destination[X_AXIS], destination[Y_AXIS], destination[Z_AXIS],
                 destination[E_AXIS] + (EXTRUDER_RUNOUT_EXTRUDE) * (EXTRUDER_RUNOUT_ESTEPS) * planner.steps_to_mm[E_AXIS],
                 MMM_TO_MMS(EXTRUDER_RUNOUT_SPEED) * (EXTRUDER_RUNOUT_ESTEPS) * planner.steps_to_mm[E_AXIS], active_extruder);

For the default settings, when the temperature is over 190, every 30 seconds the extruder will move 14 * 100 "steps" at a rate of 1500mm/m. The actual length in millimeters will depend on your extruder's STEPS_PER_UNIT setting.

I hope that makes sense.

(I'm certainly going to patch this feature before 1.1.0 is released so that we can simply specify millimeters instead.)

[thinkyhead]

@jbrazio —

It looks like the marlinfw.org domain is due to expire soon! Registry Expiry Date: 2024-03-16

We could also use IPV6 support added to the DNS.

Who wants to take the reins on this one, and who has control of the domain at this time?

[jbrazio]

I've been keeping it active since it's genesis, it has been my (small) contribution to the project for the past years. :-) I'm planning to keep renewing it until I'm asked otherwise.

If you need IPv6 support or if you need any additional DNS records it's not a problem at all and I can easily add them.

@jbrazio —

It looks like the marlinfw.org domain is due to expire soon! Registry Expiry Date: 2024-03-16

We could also use IPV6 support added to the DNS.

Who wants to take the reins on this one, and who has control of the domain at this time?

[ellensp]

@jbrazio Hello

Regarding adding IPv6

As documented on this page https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site

To create AAAA records, point your apex domain to the IP addresses for GitHub Pages.

2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

So please add a AAAA records for marlinfw.org pointing to 2606:50c0:8000::153, 2606:50c0:8001::153, 2606:50c0:8002::153 and 2606:50c0:8003::153

I have added these to my local hosts file and verified that github web server is responding to marlinfw.org over ipv6

[jbrazio]

The AAAA records were added.

nslookup marlinfw.org
Server:  UnKnown
Address:  xxx.xxx.xxx.xxx

Non-authoritative answer:
Name:    marlinfw.org
Addresses:  2606:50c0:8003::153
          2606:50c0:8000::153
          2606:50c0:8002::153
          2606:50c0:8001::153
          185.199.110.153
          185.199.111.153
          185.199.109.153
          185.199.108.153

I validated that my browser is hitting the IPv6 for the domain:

Request URL: https://marlinfw.org/
Request Method: GET
Status Code: 200 OK
Remote Address: [2606:50c0:8001::153]:443
Referrer Policy: strict-origin-when-cross-origin

[ellensp]

@jbrazio looks great, thanks