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, 15 hours ago.

Viewing 30 posts - 61 through 90 (of 159 total)
  • Author
    Posts
  • #115219

    Ryan
    Keymaster

    Heath, if each page of the instructions had a link at the top that said “click here to edit” and that brought you to a github page you can edit in the browser using markup and see a preview would that make github better for you. You then click submit and I (and hopefully others) then have the option to accept it or throw it away.

    Like Bill can directly correct my spelling and grammar easier than having to cut and paste. (my personal English teacher)

    #115220

    Ryan
    Keymaster

    I am trying to get something going but keep hitting programming hurdles. I am gunna give it another try if that doesn’t work I will clone sandify RTD and edit the whole thing.

    #115228

    Jeffeb3
    Participant

    I am gunna give it another try if that doesn’t work I will clone sandify RTD and edit the whole thing.

    But what about my copyright!! Jk.

    RTD is also a hosting service. Can you change the theme with RTD? We need more black and red.

    The mk material theme looks pretty good to me, but as long as they are markdown they should be easy to edit. Then we can figure out how to churn that using MK into Ryan’s site or RTD.

    #115229

    Jeffeb3
    Participant

    If you can get RTD to pay for the hosting, why wouldn’t you?

    #115230

    Ryan
    Keymaster

    This is embarrassing how hard this is for me….almost there.

    #115231

    Ryan
    Keymaster

    MKdocs, RTD theme (to start with), on github…..maybe

    #115232

    Ryan
    Keymaster

    OMG….https://v1engineeringinc.github.io/V1_Engineering_Docs/

    Don’t laugh it took me all that time to wrap my head around it.

    1 user thanked author for this post.
    #115235

    Ryan
    Keymaster

    Okay well that didn’t work. It outputs a bunch of working html but the plain ol docs are not there

    #115240

    Jeffeb3
    Participant

    Don’t feel bad. Setting this up is going to be the hardest part.

    I think you’ll start like this, with the “source” in github. The html output then can be pushed to another branch, which gh pages will use to host it. It looks like you’re trying to use gh pages. Ideally, the conversion to html is done automatically with a ci server whenever master changes.

    #115262

    Jeffeb3
    Participant

    Looks like there are a couple of ways to do pdf export from mkdocs. I can try them out this afternoon.

    https://github.com/zhaoterryy/mkdocs-pdf-export-plugin/blob/master/README.md

    #115304

    Heath
    Participant

    Heath, if each page of the instructions had a link at the top that said “click here to edit” and that brought you to a github page you can edit in the browser using markup and see a preview would that make github better for you. You then click submit and I (and hopefully others) then have the option to accept it or throw it away.

    Like Bill can directly correct my spelling and grammar easier than having to cut and paste. (my personal English teacher)

    That sounds intuitive enough.  I was just trying to give my feedback as a plain old reader of documentation with no experience or knowledge of the backend stuff.  But I’d love to learn and help out.

     

    #115306

    Ryan
    Keymaster

    But I’d love to learn and help out.

    HAHAHA, me too. This stuff ain’t easy. I figure If I can at least set most of it up, I will understand it enough as to make sure others can easily edit it. And, this is a test, if I can get it going and you or anyone else think it sucks….I will strongly consider other options before moving everything over.

    #115723

    Ryan
    Keymaster

    Okay progress is being made. Don’t judge this too much as this is really rough and we were just testing things out. I have learned how to make changes and deploy it to github, Hefe knew all that and figured out the rest.

    Please do not add anything to crazy yet, this all might get scrapped for a new version. If you want to try an edit feel free, I can delete the request easily.

    https://v1engineeringinc.github.io/V1EngineeringInc-Docs

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

    To see what editing a page looks like click the link at the bottom “edit on github”, towards the top of the page that pops up click on the pencil icon that is edit this page. I think I can change this link so it takes you directly to the edit page. After you make some edits you make a note and submit it at the bottom.

     

    Still to do, everything. I am not sure about this theme, It looks good but it has bugs, or I am doing something wrong. I am going to try to do the minor firmware LCD edits and mess with this a bit this evening.

     

     

    #115725

    Jeffeb3
    Participant

    I am not sure about this theme, It looks good but it has bugs, or I am doing something wrong.

    I was looking at the mkdocs-material documentation today and it seems much more mature. It said something about search not working as well with mkdocs-1.0, so I was going to try it out. It seems like it’s much friendlier to customization.

    #115728

    Ryan
    Keymaster

    I was cleaning up windmill, it has issues. The footer is not centered correctly and the menus can overlap the pages at certain times.

    Material looks good, no “edit this page on Github” I think we can add that? The page title changes with each link clicked.

    #115732

    Jeffeb3
    Participant

    The edit is the little pencil in the upper right. More info here:

    https://squidfunk.github.io/mkdocs-material/getting-started/#adding-a-source-repository

    Did you try doing the edit button with an account that wasn’t on the project? It looks like it’s going to let me just force my change through, but that might be because you added me already.

    #115733

    Ryan
    Keymaster

    Okay lets do that one then, Super easy to go back if needed.

     

    I have a start of the Sandify page to get a real look at what this will look like. I will push it now.

    #115734

    Ryan
    Keymaster

    Can you Deploy as well?

    #115735

    frosty
    Participant

    I made an edit (logged I to GitHub) and if had me fork the project, create a commit and then create a PR for it.

    1 user thanked author for this post.
    #115759

    Jeffeb3
    Participant

    Can you Deploy as well?

    Sure.

    I made an edit (logged I to GitHub) and if had me fork the project, create a commit and then create a PR for it.

    Cool! Was it confusing or difficult at all?

    #115770

    Ryan
    Keymaster

    Okay material is looking wayyyy better.

    Those docs are smoking fast, even on my phone. The Code boxes don’t resize on the phone, but don’t see how they could and I am sure these should not. Must use these sparingly.

    I am getting the hang of it now. Github gives me the commands to pull a fork if I wanted to edit it on my computer, not in a browser, still some things to learn. I can preview the changes in the browser by clicking show rich diff (everyone can! how cool!), I can also merge from the browser, then pull and deploy from the computer. I have a feeling I should make the “for dummies” manual for the back end so everyone can participate.

    So now just figure out to do with images? Anything on this server has multiple sizes but I would really like to be able to click through to a larger image. This afternoon after shipping I can look into it again.

    1 user thanked author for this post.
    #115773

    Jeffeb3
    Participant

    So now just figure out to do with images? Anything on this server has multiple sizes but I would really like to be able to click through to a larger image. This afternoon after shipping I can look into it again.

    I know you can do something like this:

    [![Step 1](url)](url)

    But if the urls are long, that is a good place for bugs to show up. There are a bunch of neat features in some python markdown extensions and one of them lets your add attributes, so we can do this for images:

    ![Step 1](url){# width=”400″}

    I posted an issue on mkdocs about the image zoom. I wonder if we can add some js or something to the theme. Otherwise, maybe we could make our own python-markdown extension. I can’t imagine no one has done this before though.

    #115879

    Ryan
    Keymaster

    Dang you work fast. I committed the changes but have not deployed them yet. Adding js is just like css right, a new file and the current one over rights the theme? To change the highlight bar I believe we need a js edit anyway.

    I think I am going to make the max page a little wider? Speak now or forever hold your piece.

     

    Is this all that is needed to auto deploy, one yml file? https://docs.travis-ci.com/user/deployment/pages/

    #115933

    Jeffeb3
    Participant

    The cs and the javascript aren’t writing over anything. They just add more settings. If the css conflicts, the later one gets used.

    I think I am going to make the max page a little wider? Speak now or forever hold your piece.

    The max page? Like the main part? Just be careful it doesn’t mess with the mobile formatting. The mobile is great.

    #115935

    Jeffeb3
    Participant

    Is this all that is needed to auto deploy, one yml file? https://docs.travis-ci.com/user/deployment/pages/%5B/quote%5D

    I actually saw someone with a travis file for mkdocs and I made a note to go check that out. I’m sure there are some nuances, and we’ll need to keep the requirements
    txt up to date, but yeah, that’s the idea.

    #116304

    Ryan
    Keymaster

    Wowzers, looking solid now. I figured out how to do some more backend stuff all by myself (with google). Jeff has it all buttoned up I think.

    Questions, comments, suggestions?

    https://v1engineeringinc.github.io/V1EngineeringInc-Docs/mkdocs_info/

    I think a style is just needed now. As much as I want to put the images in a table I know it is too much of a hassle. Any way to get these in line? I tried just moving the images in the .md not to have a return just a space. Didn’t work.

    https://v1engineeringinc.github.io/V1EngineeringInc-Docs/pg1/#corner-lower-assembly

     

    PS, linking directly to the step is freaking awesome!

    #116308

    Ryan
    Keymaster

    Link color suggestion?

    Might be too much red to make that red as well, dark grey, darker red?

    Jamie has a basic page in there, looking for  style before trying to move other things over.

    https://v1engineeringinc.github.io/V1EngineeringInc-Docs/pg1/

    #116313

    Jeffeb3
    Participant

    screenshot-2019-10-01-1569983400

    The top is a table, like this:

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

    The table looks hideous in the text and is prone to errors.

    The bottom is with an align call, that I found with google, but if you don’t add a bunch of white space, it gets odd.

    ![!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"}
    <br/>
    <br/>
    <br/>
    <br/>
    <br/>
    <br/>
    <br/>
    <br/>
    <br/>
    <br/>
    <br/>
    

    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?

    #116316

    Jeffeb3
    Participant

    I’m also a bit curious. Frosty and Jamie made a PR. Did the rest of you not try it? Or did you try it and then hit a problem?

    I think if there are any problems, now would be a great time to work through them, or document how to get around them before we frustrate some potential big contributors.

    #116321

    Jeffeb3
    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.

Viewing 30 posts - 61 through 90 (of 159 total)

You must be logged in to reply to this topic.