Community Documentation

New Home Forum Software / Firmware Development Community Documentation

This topic contains 158 replies, has 15 voices, and was last updated by  Jeffeb3 4 days, 14 hours ago.

Viewing 30 posts - 91 through 120 (of 159 total)
  • Author
    Posts
  • #116323

    Tim
    Participant
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    ![!bottom and lock corner apart](https://www.v1engineering.com/wp-content/uploads/2016/08/IMG_20160823_115926.jpg){: width="400" align="left"}
    ![!bottom and lock corner together](https://www.v1engineering.com/wp-content/uploads/2016/08/IMG_20160823_120220.jpg){: width="200" align="left"}











    The align isn’t so bad, but the br’s is definitely going to bite us. Someone here must know a better way. We can add classes to the images with the {} in the markdown. So maybe that will let us fix it in .css? Something like class=”image-table” and then in css do something? @twolf?

    I’m not sure what the behavior is if you don’t put the line breaks, but I am assuming if you wrap the images in a div tag (because it has a default display mode of block, vs default image display mode of inline block) it should keep stuff from floating right up to it. (I am assuming the issue is that, not 100% sure) You can also style that div with a class like you said, adding some margin-bottom/padding-bottom if that’s what the issue is.

    1 user thanked author for this post.
    #116324

    Tim
    Participant

    More on the images. I looked for some good examples of image collections in mkdocs, and I didn’t find much. There is a javascript library called lightbox, and I saw this awesome example:

    https://jitaku.work/it/mkdocs/gallery/

    Even translated, I couldn’t get it to work. But there must be a way.

    https://gist.github.com/trusktr/93175b620d47827ffdedbf52433e3b37#file-image-grid-md

    1 user thanked author for this post.
    #116326

    Ryan
    Keymaster

    Whoa, sorry I was messing with the same thing.

    Tables look okay but I think editing them is too intimidating for most. I can try to style the pictures and text another way.

     

     

    #116327

    Ryan
    Keymaster

    I saw a css class that changed it from block to inline, but lost the page somehow. Not sure it would work but it is what I was looking for. If you had them listed they would go inline and at least one line between them they would do as they currently do.

    #116329

    Jeffeb3
    Participant

    I’m not sure what the behavior is if you don’t put the line breaks, but I am assuming if you wrap the images in a div tag (because it has a default display mode of block, vs default image display mode of inline block) it should keep stuff from floating right up to it. (I am assuming the issue is that, not 100% sure) You can also style that div with a class like you said, adding some margin-bottom/padding-bottom if that’s what the issue is.

    The text just wraps around it.

    Markdown is a bit funny. Anything inside an html tag won’t get parsed anymore, so if I add a div, I can’t use the markdown for the images, I have to use img tags. That’s not ideal.

    The gist is using a table. I can probably format that a little nicer.

    #116330

    Ryan
    Keymaster

    Added a link to the first post, hope that is okay Heffe?

    So if we have to choose between the larger image (lightgallery) or a pretty grid, I choose larger image. The instructions can just get formatted broken down further, picture of parts – parts list, picture of assembled parts – description of that step. Longer page but the pages get indexes when you open them anyway so it should be okay? Heck maybe it is easier that way for first timers.

    #116331

    Jeffeb3
    Participant

    Whoa, sorry I was messing with the same thing.

    That’s ok. That’s why I came back here, to invoke the hive mind. Remember I know (git) kung-fu. But I won’t be keeping these changes anyway.

    Tables look okay but I think editing them is too intimidating for most. I can try to style the pictures and text another way.

    There must be a good way to organize this. The further we go down customizations, the harder it will be to switch markdown compilers and to create a sane pdf document. Keeping closer to the standard markdown should make our lives easier, and easier for people to edit. I’m just wondering what other mkdocs/markdown instructions look like.

    w.r.t. the foot, it could be as simple as putting the after photo after the instructions or something. IDK.

    It’s worth thinking about it for a bit, but I still have the impression that soon, we need to just copy-paste what you have into the new site, and then start reviewing and editing it. If we do them at the same time, we’ll never finish.

    #116332

    Jeffeb3
    Participant

    Added a link to the first post, hope that is okay Heffe?

    Totally fine. Thanks for making it obvious what you changed.

    So if we have to choose between the larger image (lightgallery) or a pretty grid, I choose larger image

    The light gallery works fine with the table. Also, in that picture, I shrunk the before image to 200 width just to see them better.

    The thing I don’t like about the table is just that it ends up being this enormous line with even two images, and it becomes very hard to edit or review. It looks great in the final page.

    |![!foot apart](https://www.v1engineering.com/wp-content/uploads/2016/08/IMG_20160823_115308.jpg){: width="400"}|![!foot together](https://www.v1engineering.com/wp-content/uploads/2016/08/IMG_20160823_115352.jpg){: width="150"} |
    |:–:|:–:|
    |before|after|
    

    Try this, it looks good, but it’s just a pain to look at in the .md.

    The instructions can just get formatted broken down further, picture of parts – parts list, picture of assembled parts – description of that step. Longer page but the pages get indexes when you open them anyway so it should be okay? Heck maybe it is easier that way for first timers.

    That might be true. Probably part of the first edit. Maybe just leave it as is for now, and only make a table for the ones that are hard to put in line with text/headings?

    #116333

    Ryan
    Keymaster

    Gotcha, I added a page Step 3. The first two “steps” have an image and either a parts list or instructions.

    Format the pics to a standard height or width, for instructions? Maybe height, since it is a scrolling list?

    #116334

    Jeffeb3
    Participant

    Sounds good to me.

    #116335

    Ryan
    Keymaster

    Oops, width looks better. 400 seems good. Ending each looks pretty good with a horizontal line, ___, gives it a little differentiation or something.

    #116709

    Jeffeb3
    Participant

    I went through the v1engineering docs and made a first pass at a tree of what is there. I put a dummy file in for each one and I put them all in a PR:

    https://github.com/V1EngineeringInc/V1EngineeringInc-Docs/pull/10

    Next is, we need to convert the pages from v1 to github. There’s a lot of content there and it will take a while to move it all, so it would be great if some of the community would volunteer to do some pages. Here’s how I think we can do it to avoid trouble:

    1) In this forum post, point out which page you’re going to edit. The first person to post about it will edit it.

    2) Click on the pencil in the top right of a page. The first link on the page should be to the v1engineering site where the content is coming from. Copy text, Make similar headings, and put the same images back in. A couple tips:

    * It will be really tempting to “edit” and “author” new stuff right away. For the sake of git and a reduction in chaos, it will be a lot cleaner if you just copy it as-is first. If you see a misspelled word, go ahead and fix it, but don’t rewrite sentences completely (yet).

    * You can right-click on an image at v1engineering.com and select “copy image location”. That is the address of the image you can put into markdown.

    * If you are having trouble making links or linking images, just point it out to us, and we’ll fix it before merging it in.

    3) Edit the about.md page and add yourself as a contributor.

    4) Make a Pull Request, which I think git will help you with when you click on the pencil in the top right of a page. Ryan and/or I will check it out, maybe do one or two items of polish to make sure all the links are right, merge it, and then deploy it to the website.

    After we’ve got the pages up, we can start looking hard at editing or reorganizing things. Having the info in markdown format makes it much easier to move around or change. Just making this documentation at least as useful as the original is a huge step forward, and we need to get there soon, or Ryan will go nuts trying to change two pages while there are still two copies.

    #116711

    Jeffeb3
    Participant
    ├── electronics
    │   ├── dual-endstops.md
    │   ├── index.md
    │   ├── marlin-firmware.md
    │   ├── ramps.md
    │   ├── steppers.md
    │   ├── ultimachine.md
    │   └── v1pi.md
    ├── lowrider
    │   └── index.md
    ├── mp3dp
    │   └── index.md
    ├── mpcnc
    │   ├── base.md – Jamie/vector76
    │   ├── belts.md
    │   ├── conduit.md
    │   ├── final.md
    │   ├── gantry.md
    │   ├── index.md
    │   ├── middle-assm.md
    │   ├── table.md
    │   └── z-axis.md
    ├── software
    │   ├── estlcam-2p5d.md
    │   ├── estlcam-basics.md
    │   ├── index.md
    │   ├── repetier-host.md
    │   └── reverse-motor.md
    ├── tools
    │   ├── drag-knife.md
    │   ├── import-extruder.md
    │   ├── laser-engraving-mirrors.md
    │   ├── lasers.md
    │   └── milling-basics.md
    └── zenxy
        └── index.md – Ryan/vicious1
    

    I count 26 pages left. Not too bad, since we don’t have to type them all out.

    • This reply was modified 2 weeks, 1 day ago by  Jeffeb3.
    • This reply was modified 2 weeks, 1 day ago by  Jeffeb3.
    • This reply was modified 2 weeks, 1 day ago by  Jeffeb3. Reason: Added mp3dp
    #116726

    Bill
    Participant

    Are you missing the MP3DP there, or is it already done?

    #116729

    Jeffeb3
    Participant

    It is missing. I made a note of it, but I’m waiting for Ryan to fix it.

    #116744

    Jeffeb3
    Participant

    I went ahead and added it. It’s currently only one (very long) page.

    #116754

    Ryan
    Keymaster

    Beast mode Heffe! Rough couple of weeks for me but I hope things are getting back to normal, Inventory is shipping and inbound, house is no longer flooded, water is not leaking out of my main waterline, sewer is fixed, firmware is up to date (relatively), github docs work, hate mail is slowing considerably.

    I am beat for the day but I am eager to get at it early tomorrow.

    In the evening tomorroe, I hope to put some time into a few pages myself. I appreciate the help all of you have given thus far. I figure if we get a few more pages done maybe I can put a front page post up to get things kick started.

    #116777

    Jeffeb3
    Participant

    I merged and deployed that PR. Ready for edits.

    1 user thanked author for this post.
    #117325

    Jeffeb3
    Participant

    I’m working on converting:

    software/estlcam-2p5d.md
    software/estlcam-basics.md
    software/index.md

    1 user thanked author for this post.
    #117328

    Bruh
    Participant

    Do you all have this set up to auto deploy on merges back into master? It’d be easy enough to have https://travis-ci.org/ build and deploy docs out to where ever. If you’re going the GitHub route I’d recommend going ahead and setting up a GitHub Organization. As far as gating what goes back into master you can set up GitHub CodeOwners to require that certain individuals/teams review pull requests. You can even assign code owners to specific directories/files so that no one person has to be an expert on everything. I will say that all of this is a bit more developer-centric that some users may like but it doesn’t bother me 🙂

    Happy to give a hand setting up TravisCI to auto build/deploy if you all would like.

    Edit: Set up GitHub branch protection on master to prevent @jeffeb3 from force pushing. 😉

    • This reply was modified 1 week, 3 days ago by  Bruh.
    • This reply was modified 1 week, 3 days ago by  Bruh.
    2 users thanked author for this post.
    #117331

    frosty
    Participant

    I’ll take assembly/middle for the MPCNC

     

    2 users thanked author for this post.
    #117333

    Jeffeb3
    Participant

    Do you all have this set up to auto deploy on merges back into master? It’d be easy enough to have https://travis-ci.org/ build and deploy docs out to where ever.

    It’s not. Travis seems easy enough to set up, but the commercial version is too expensive ($63/month, IIRC). I was thinking there must be something we could do on a pi to do the same thing. But it literally takes 30 seconds to do it if I’m not already at my computer. If I am already at my computer merging changes, then it’s basically free. Travis has the advantage of not fat fingering a deploy and always deploying the right commit though.

    Edit: Set up GitHub branch protection on master to prevent @jeffeb3 from force pushing. 😉

    I definitely would do this if it were my repo. Ryan has given me some permissions, but I can’t tweak branch permissions. I would also only allow merge commits from PRs, but I given the audience, I don’t want to make it too hard. The easiest time to sell permissions like that is right after a problem :).

    Now that things are basically started, I’m assuming it’s Ryan’s responsibility to at least approve PRs. I’ll do what I can to review them and do minor tests. When we get more contributions, I assume some other permissioned volunteers will become obvious. If I notice gh pages is out of date, I might use my powers to deploy, but otherwise not.

    #117334

    Jeffeb3
    Participant

    I’m working on converting:

    software/estlcam-2p5d.md

    software/estlcam-basics.md

    software/index.md

    FWIW, these pages took about 20 minutes each. The hardest part was copying the links and images. I was trying hard not to type anything, just copy paste. But my mousing is slow.

    #117337

    frosty
    Participant

    Ugh. Python and I do not get along at all…

    I cloned the repo, and have done the following trying to get mkdocs to work:

     

    385 pip install mkdocs
    386 sudo pip install mkdocs
    387 cd V1EngineeringInc-Docs/

    393 mkdocs serve
    394 sudo pip install pymdown-extensions
    395 mkdocs serve
    396 sudo pip install pyembed-markdown
    397 mkdocs serve

    413 git clone https://github.com/g-provost/lightgallery-markdown
    414 cd lightgallery-markdown/
    415 python setup.py install
    416 sudo python setup.py install
    417 cd ..
    418 mkdocs serve

    And here’s where I am now:

    INFO – Building documentation…
    ERROR – Config value: ‘theme’. Error: Unrecognised theme name: ‘material’. The available installed themes are: readthedocs, mkdocs

    I’m at the point where I think python is some elaborate decade-long practical joke on me. Literally every time I’ve tried to use it for anything I would follow the instructions and it would end up in this unresolved dependency quagmire…

    ETA: sudo pip install mkdocs-material was the missing link. Got it going now.

    Is there a better way to do that? If so, please tell me and put it in the ‘getting started’ section of the repo…

    • This reply was modified 1 week, 3 days ago by  frosty.
    1 user thanked author for this post.
    #117339

    Jeffeb3
    Participant

    Oh shoot. I should make that easier to find. I don’t know what system you’re on, and I only know Linux :).

    You’re real close. Assuming pip permissions are ok, you just need to install mkdocs-material.

    https://v1engineeringinc.github.io/V1EngineeringInc-Docs/mkdocs_info/#installing-dependencies

    What I do is:

    – Clone the repo and cd into it.
    – virtualenv -p python3 venv #this may nit be exactly the syntax.
    – source ./venv/bin/activate
    – pip install -r requirements.txt
    – mkdocs serve

    Pip can install a ton of things pretty darn quickly, so if I use it outside of a virtualenv, I do pip install –user <package>. That can still be pretty dangerous in general though.

    This is just if you want to run mkdocs. You can also edit in github if you feel like it.

    Thanks for pushing through.

    1 user thanked author for this post.
    #117343

    Bruh
    Participant

    Do you all have this set up to auto deploy on merges back into master? It’d be easy enough to have https://travis-ci.org/ build and deploy docs out to where ever.

    It’s not. Travis seems easy enough to set up, but the commercial version is too expensive ($63/month, IIRC). I was thinking there must be something we could do on a pi to do the same thing. But it literally takes 30 seconds to do it if I’m not already at my computer. If I am already at my computer merging changes, then it’s basically free. Travis has the advantage of not fat fingering a deploy and always deploying the right commit though.

    Edit: Set up GitHub branch protection on master to prevent @jeffeb3 from force pushing. 😉

    I definitely would do this if it were my repo. Ryan has given me some permissions, but I can’t tweak branch permissions. I would also only allow merge commits from PRs, but I given the audience, I don’t want to make it too hard. The easiest time to sell permissions like that is right after a problem :).

    Now that things are basically started, I’m assuming it’s Ryan’s responsibility to at least approve PRs. I’ll do what I can to review them and do minor tests. When we get more contributions, I assume some other permissioned volunteers will become obvious. If I notice gh pages is out of date, I might use my powers to deploy, but otherwise not.

    @jeffeb3 I’m just pulling your leg about force pushing to master! Definitely appreciate the desire to make docs more accessible / crowd sourced.

    TravisCI is free for open source repositories. Not sure if licenses and such make that an issue for this use case.

    Added benefit of TravisCI is that Ryan wouldn’t have to distribute deploy keys to anyone. PRs drive documentation changes and people are completely taken out of the loop to see changes deployed.

    Happy to lend a hand if you’d like.

    forcepush

    • This reply was modified 1 week, 3 days ago by  Bruh.
    • This reply was modified 1 week, 3 days ago by  Bruh.
    Attachments:
    #117347

    Jeffeb3
    Participant

    No worries. I knew it was a joke.

    TravisCI is free for open source repositories. Not sure if licenses and such make that an issue for this use case.

    I really don’t know. The documentation and the machine have an NC license right now. Not sure where the rules are.

    The deploy is just pushing to the gh-pages, so the permissions are currently managed by github. There aren’t any branch permissions, but Ryan could make the same permissions on gh-pages as master.

    #117349

    Ryan
    Keymaster

    Circle CI is free for a basic ?build? is it the same thing? Most of the things you are talking about is above my pay grade but know I am furiously googling to try and understand…

    #117350

    Jeffeb3
    Participant

    https://circleci.com/docs/

    Looks like a friendly service. I can check it out after the kiddos go to bed.

    #117351

    Bruh
    Participant

    Circle CI is free for a basic ?build? is it the same thing? Most of the things you are talking about is above my pay grade but know I am furiously googling to try and understand…

    They’re competitors and more or less the same thing, yeah. I don’t think the licensing is going to be a big issue either way so pick whatever is easier to set up. I only mentioned it because it was brought up earlier in the thread.

    mkdocs itself uses travis, fwiw: https://github.com/mkdocs/mkdocs/blob/master/.travis.yml

    • This reply was modified 1 week, 3 days ago by  Bruh.
Viewing 30 posts - 91 through 120 (of 159 total)

You must be logged in to reply to this topic.