New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature/1332 use mk docs for docs.versionpress.net #1334

Merged
merged 70 commits into from Jun 13, 2018

Conversation

2 participants
@lisaross
Contributor

lisaross commented May 28, 2018

Resolves #1332
(I think)

Lots of files and configurations changed but I've done my best to document how and what was done.

Some highlights:

  • moved files into structure that is more audience specific (ie. developer vs user, as well as making more multilang friendly when the time comes)
  • mkdocs runs it all, with material theme bringing features like search
  • theme uses material for function but modded to create similar look/feel to existing .net
  • switched out markdown note engine from html to admonition and refactored documentation
  • functionality for theme override in place with instructions in readme
  • tested docs to ensure links aren't broken

Still to do

  • not sure how you want to deploy - left it in the README for you to decide and we can update the docs as needed
  • mkdocs doesn't have a great system in place for redirection, in the event that we want to point someone to the new link should they land on an old one. Depending on how we deploy, we can either use server side redirection using .htaccess for example, or we can create files in old location that manually redirect to new. I would say we should open a new issue for redirection and go from there though.

Some notes

  • this is actually my first pull request ever, so please be kind if I've screwed something up. 💃
  • if you have any questions about how something works please let me know
  • realized after the fact that this should have been tagged 'improvement' rather than 'feature' I think. Sorry.
  • wasn't sure if you have any automated tests in place for this - if so, please point me in the right direction. If not, I'd love to work with someone to see about making them.
  • don't hesitate to punt it back to me if it's a disaster. I only just started using git, for example, so if my commits aren't to standard I'd love coaching on that (or anything, for that matter)

@borekb 🏁 notes:

This is an awesome PR and a nice refresh of our docs, thanks @lisaross! Highlights from my point of view are:

  • Static site hosted on GitHub Pages instead of a custom Node.js app that was bothersome to run and maintain.
  • Developer documentation is now part of the docs as well.
  • Much easier contributions via GitHub pull requests – there's an edit button on each page.
  • We use a standard documentation system, MkDocs, instead of a custom one.

New site:

image

Original site:

image

@borekb

This comment has been minimized.

Member

borekb commented Jun 3, 2018

At this point, I'm pretty happy with the new docs. The system is really nice to work with, there are Edit buttons for easy content updates, the old URLs still work, the design is an interesting blend of material and our original look, etc. Good stuff.

The rest of the work should be mostly visual (transparent header, better contrast in some cases, customized footer) and technical (content/img -> CDN, incorrect URL for GitHub and Twitter icons in the footer). We're close.

@borekb

This comment has been minimized.

Member

borekb commented Jun 7, 2018

@lisaross Thanks for the visual fixes in c4bae26, it's much better now.

I've also merged in master which now contains a major update of dev-setup.md from PR #1329.

This evening, I should find some time to look at this PR again, work on the smaller remaining issues and hopefully get it prepared for merge.

@lisaross

This comment has been minimized.

Contributor

lisaross commented Jun 7, 2018

@lisaross

This comment has been minimized.

Contributor

lisaross commented Jun 8, 2018

Gah! I just merged something into master without meaning to I think... please rewind if needed, @borekb

Edit: oh good. I think I just gave myself an unneeded heart attack LMAO

@borekb

This comment has been minimized.

Member

borekb commented Jun 8, 2018

Yeah, everything is alright :) Actually, GitHub would prevent any accidental push to master so you'll safe.

@lisaross

This comment has been minimized.

Contributor

lisaross commented Jun 8, 2018

Ya I realized that after I typed. Of course you wouldn't let someone with a single pull request push to master lmao. That last commit was just adding your socnets to the footer - I was going to mod the whole footer file to make it look like .net, but realized that was probably enough and kept it simple. If you want me to make further mods just make me a list and I'll work on it tomorrow. Otherwise, I think the styling is ok for now? Or did I miss something?

@borekb

This comment has been minimized.

Member

borekb commented Jun 8, 2018

I was going to mod the whole footer file to make it look like .net, but realized that was probably enough and kept it simple.

Yep, I actually like the current footer very much – keeps the style of previous docs but is more useful / modern.

Otherwise, I think the styling is ok for now? Or did I miss something?

Generally, I think it looks awesome, just the contrast of the search box is sometimes not great, e.g., on hover. Do you want to look into that? I could also experiment with it a bit.

@borekb

This comment has been minimized.

Member

borekb commented Jun 8, 2018

I'm looking at the styles, for example, setting the theme.palette.primary value to a hex value doesn't seem to have any effect. Give me a few moments to review this, thanks.

@borekb

This comment has been minimized.

Member

borekb commented Jun 8, 2018

I've done some slight visual fixes in 070f528, I'm happy with it now.

Still to-do (plan to do this tonight):

  • logo.png is too small for mobile view with sidebar opened - it's pixelated. Plus, upload to CDN. d720e6a
  • Sort out favicon. d720e6a
  • H5 is too big d1bde7a
  • Review content d898e02
  • Lint Markdown files manually ee49284

borekb added some commits Jun 8, 2018

logo.png is now in better resolution and uploaded to CDN, same for fa…
…vicon (Material theme doesn't support it seamlessly so there is a template customization in main.html)
@borekb

This comment has been minimized.

Member

borekb commented Jun 13, 2018

Hi @lisaross, sorry for the delay, I think I'll find time today evening to have a look at the GitHub Pages deployment (just document the manual process in README) and then I'd be happy to merge this PR. Is that fine with you? Anything else you would like to look at? Thanks.

@lisaross

This comment has been minimized.

Contributor

lisaross commented Jun 13, 2018

oh my goodness, don't apologize! 😄Let's do it! I didn't get a chance to look at the search styles, but we can probably do a minor after the PR is merged, yes? Thanks for including me in this process btw. I love that I've been able to contribute.

@borekb

This comment has been minimized.

Member

borekb commented Jun 13, 2018

Thanks. I'll probably write a quick blog post about the new docs and would like to credit you, do you have a Twitter profile or something that you'd prefer me to use? Your contribution has been awesome!

@lisaross

This comment has been minimized.

Contributor

lisaross commented Jun 13, 2018

WOW! THANKS! My twitter profile is @iamlisaross but I've updated my github profile to display info instead if that's easier/better. 👍 https://github.com/lisaross

@borekb

This comment has been minimized.

Member

borekb commented Jun 13, 2018

🎉 the docs site is now updated and runs on GitHub Pages: https://docs.versionpress.net/

I'll make some final notes in this PR later tonight and merge.

@borekb borekb merged commit 4a78282 into versionpress:master Jun 13, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

4.0 beta -> final automation moved this from In Progress to Done Jun 13, 2018

This was referenced Jun 13, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment