What if I don't update a documentation?
@@ -41,10 +41,15 @@ app.templates.offlinePage = (docs) -> """
"""
canICloseTheTab = ->
- if app.AppCache.isEnabled()
+ if app.ServiceWorker.isEnabled()
""" Yes! Even offline, you can open a new tab, go to devdocs.io , and everything will work as if you were online (provided you installed all the documentations you want to use beforehand). """
else
- """ No. AppCache isn't available in your browser (or is disabled), so loading devdocs.io offline won't work.ENABLE_SERVICE_WORKER environment variable to true)"
+
+ """ No. Service Workers #{reason}, so loading devdocs.io offline won't work.Thanks for downloading DevDocs. Here are a few things you should know:
Your local version of DevDocs won't self-update. Unless you're modifying the code,
- I recommend using the hosted version at devdocs.io .
+ we recommend using the hosted version at devdocs.io .
Run thor docs:list to see all available documentations.
Run thor docs:download <name> to download documentations.
Run thor docs:download --installed to update all downloaded documentations.
@@ -39,7 +39,7 @@ app.templates.intro = """
DevDocs works offline , on mobile, and can be installed on Chrome .
For the latest news, follow @DevDocs .
DevDocs is free and open source .
-
+ And if you're new to coding, check out freeCodeCamp's open source curriculum .
Happy coding!
diff --git a/assets/javascripts/templates/pages/settings_tmpl.coffee b/assets/javascripts/templates/pages/settings_tmpl.coffee
index 1d439edb..94afe3df 100644
--- a/assets/javascripts/templates/pages/settings_tmpl.coffee
+++ b/assets/javascripts/templates/pages/settings_tmpl.coffee
@@ -15,6 +15,14 @@ app.templates.settingsPage = (settings) -> """
Tip: drag the edge of the sidebar to resize it.
+
+ Only enable this when bandwidth isn't a concern to you.
+
+
+ With this checked, we enable Google Analytics and Gauges to collect anonymous traffic information.
+
diff --git a/assets/javascripts/tracking.js b/assets/javascripts/tracking.js
index ca05b218..a68ca493 100644
--- a/assets/javascripts/tracking.js
+++ b/assets/javascripts/tracking.js
@@ -1,28 +1,32 @@
try {
- if (app.config.env == 'production') {
- (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
- (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
- m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
- })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
- ga('create', 'UA-5544833-12', 'devdocs.io');
- page.track(function() {
- ga('send', 'pageview', {
- page: location.pathname + location.search + location.hash,
- dimension1: app.router.context && app.router.context.doc && app.router.context.doc.slug_without_version
+ if (app.config.env === 'production') {
+ if (Cookies.get('analyticsConsent') === '1') {
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+ ga('create', 'UA-5544833-12', 'devdocs.io');
+ page.track(function() {
+ ga('send', 'pageview', {
+ page: location.pathname + location.search + location.hash,
+ dimension1: app.router.context && app.router.context.doc && app.router.context.doc.slug_without_version
+ });
});
- });
- page.track(function() {
- if (window._gauges)
- _gauges.push(['track']);
- else
- (function() {
- var _gauges=_gauges||[];!function(){var a=document.createElement("script");
- a.type="text/javascript",a.async=!0,a.id="gauges-tracker",
- a.setAttribute("data-site-id","51c15f82613f5d7819000067"),
- a.src="https://secure.gaug.es/track.js";var b=document.getElementsByTagName("script")[0];
- b.parentNode.insertBefore(a,b)}();
- })();
- });
+ page.track(function() {
+ if (window._gauges)
+ _gauges.push(['track']);
+ else
+ (function() {
+ var _gauges=_gauges||[];!function(){var a=document.createElement("script");
+ a.type="text/javascript",a.async=!0,a.id="gauges-tracker",
+ a.setAttribute("data-site-id","51c15f82613f5d7819000067"),
+ a.src="https://secure.gaug.es/track.js";var b=document.getElementsByTagName("script")[0];
+ b.parentNode.insertBefore(a,b)}();
+ })();
+ });
+ } else {
+ resetAnalytics();
+ }
}
} catch(e) { }
diff --git a/assets/javascripts/views/content/content.coffee b/assets/javascripts/views/content/content.coffee
index 8c5ba874..4e01733e 100644
--- a/assets/javascripts/views/content/content.coffee
+++ b/assets/javascripts/views/content/content.coffee
@@ -153,6 +153,9 @@ class app.views.Content extends app.View
return
afterRoute: (route, context) =>
+ if route != 'entry' and route != 'type'
+ resetFavicon()
+
switch route
when 'root'
@show @rootPage
diff --git a/assets/javascripts/views/content/entry_page.coffee b/assets/javascripts/views/content/entry_page.coffee
index beae4d77..f6f06511 100644
--- a/assets/javascripts/views/content/entry_page.coffee
+++ b/assets/javascripts/views/content/entry_page.coffee
@@ -40,6 +40,7 @@ class app.views.EntryPage extends app.View
if app.disabledDocs.findBy 'slug', @entry.doc.slug
@hiddenView = new app.views.HiddenPage @el, @entry
+ setFaviconForDoc(@entry.doc)
@delay @polyfillMathML
@trigger 'loaded'
return
@@ -123,7 +124,7 @@ class app.views.EntryPage extends app.View
@render @tmpl('pageLoadError')
@resetClass()
@addClass @constructor.errorClass
- app.appCache?.update()
+ app.serviceWorker?.update()
return
cache: ->
diff --git a/assets/javascripts/views/content/settings_page.coffee b/assets/javascripts/views/content/settings_page.coffee
index e39b17df..9ca606c6 100644
--- a/assets/javascripts/views/content/settings_page.coffee
+++ b/assets/javascripts/views/content/settings_page.coffee
@@ -1,7 +1,4 @@
class app.views.SettingsPage extends app.View
- LAYOUTS = ['_max-width', '_sidebar-hidden', '_native-scrollbars']
- SIDEBAR_HIDDEN_LAYOUT = '_sidebar-hidden'
-
@className: '_static'
@events:
@@ -17,31 +14,31 @@ class app.views.SettingsPage extends app.View
settings.dark = app.settings.get('dark')
settings.smoothScroll = !app.settings.get('fastScroll')
settings.arrowScroll = app.settings.get('arrowScroll')
- settings[layout] = app.settings.hasLayout(layout) for layout in LAYOUTS
+ settings.autoInstall = app.settings.get('autoInstall')
+ settings.analyticsConsent = app.settings.get('analyticsConsent')
+ settings[layout] = app.settings.hasLayout(layout) for layout in app.settings.LAYOUTS
settings
getTitle: ->
'Preferences'
toggleDark: (enable) ->
- html = document.documentElement
- html.classList.toggle('_theme-default')
- html.classList.toggle('_theme-dark')
app.settings.set('dark', !!enable)
- app.appCache?.updateInBackground()
return
toggleLayout: (layout, enable) ->
- document.body.classList[if enable then 'add' else 'remove'](layout) unless layout is SIDEBAR_HIDDEN_LAYOUT
- document.body.classList[if $.overlayScrollbarsEnabled() then 'add' else 'remove']('_overlay-scrollbars')
app.settings.setLayout(layout, enable)
- app.appCache?.updateInBackground()
return
toggleSmoothScroll: (enable) ->
app.settings.set('fastScroll', !enable)
return
+ toggleAnalyticsConsent: (enable) ->
+ app.settings.set('analyticsConsent', if enable then '1' else '0')
+ resetAnalytics() unless enable
+ return
+
toggle: (name, enable) ->
app.settings.set(name, enable)
return
@@ -85,6 +82,8 @@ class app.views.SettingsPage extends app.View
@toggleSmoothScroll input.checked
when 'import'
@import input.files[0], input
+ when 'analyticsConsent'
+ @toggleAnalyticsConsent input.checked
else
@toggle input.name, input.checked
return
diff --git a/assets/javascripts/views/content/type_page.coffee b/assets/javascripts/views/content/type_page.coffee
index 147fa7ed..ef360c14 100644
--- a/assets/javascripts/views/content/type_page.coffee
+++ b/assets/javascripts/views/content/type_page.coffee
@@ -9,6 +9,7 @@ class app.views.TypePage extends app.View
render: (@type) ->
@html @tmpl('typePage', @type)
+ setFaviconForDoc(@type.doc)
return
getTitle: ->
diff --git a/assets/javascripts/views/layout/document.coffee b/assets/javascripts/views/layout/document.coffee
index 02b98c7a..597dfe37 100644
--- a/assets/javascripts/views/layout/document.coffee
+++ b/assets/javascripts/views/layout/document.coffee
@@ -75,9 +75,11 @@ class app.views.Document extends app.View
return unless target.hasAttribute('data-behavior')
$.stopEvent(event)
switch target.getAttribute('data-behavior')
- when 'back' then history.back()
- when 'reload' then window.location.reload()
- when 'reboot' then app.reboot()
- when 'hard-reload' then app.reload()
- when 'reset' then app.reset() if confirm('Are you sure you want to reset DevDocs?')
+ when 'back' then history.back()
+ when 'reload' then window.location.reload()
+ when 'reboot' then app.reboot()
+ when 'hard-reload' then app.reload()
+ when 'reset' then app.reset() if confirm('Are you sure you want to reset DevDocs?')
+ when 'accept-analytics' then Cookies.set('analyticsConsent', '1') && app.reboot()
+ when 'decline-analytics' then Cookies.set('analyticsConsent', '0') && app.reboot()
return
diff --git a/assets/javascripts/views/layout/resizer.coffee b/assets/javascripts/views/layout/resizer.coffee
index 86bb46f5..5584bfbe 100644
--- a/assets/javascripts/views/layout/resizer.coffee
+++ b/assets/javascripts/views/layout/resizer.coffee
@@ -11,9 +11,6 @@ class app.views.Resizer extends app.View
init: ->
@el.setAttribute('draggable', 'true')
@appendTo $('._app')
-
- @style = $('style[data-resizer]')
- @size = @style.getAttribute('data-size')
return
MIN = 260
@@ -24,15 +21,11 @@ class app.views.Resizer extends app.View
return unless value > 0
value = Math.min(Math.max(Math.round(value), MIN), MAX)
newSize = "#{value}px"
- @style.innerHTML = @style.innerHTML.replace(new RegExp(@size, 'g'), newSize)
- @size = newSize
- if save
- app.settings.setSize(value)
- app.appCache?.updateInBackground()
+ document.documentElement.style.setProperty('--sidebarWidth', newSize)
+ app.settings.setSize(value) if save
return
onDragStart: (event) =>
- @style.removeAttribute('disabled')
event.dataTransfer.effectAllowed = 'link'
event.dataTransfer.setData('Text', '')
$.on(window, 'dragover', @onDrag)
diff --git a/assets/javascripts/views/layout/settings.coffee b/assets/javascripts/views/layout/settings.coffee
index 7888118a..6941b9cd 100644
--- a/assets/javascripts/views/layout/settings.coffee
+++ b/assets/javascripts/views/layout/settings.coffee
@@ -25,7 +25,6 @@ class app.views.Settings extends app.View
if super
@render()
document.body.classList.remove(SIDEBAR_HIDDEN_LAYOUT)
- app.appCache?.on 'progress', @onAppCacheProgress
return
deactivate: ->
@@ -33,7 +32,6 @@ class app.views.Settings extends app.View
@resetClass()
@docPicker.detach()
document.body.classList.add(SIDEBAR_HIDDEN_LAYOUT) if app.settings.hasLayout(SIDEBAR_HIDDEN_LAYOUT)
- app.appCache?.off 'progress', @onAppCacheProgress
return
render: ->
@@ -52,7 +50,7 @@ class app.views.Settings extends app.View
docs = @docPicker.getSelectedDocs()
app.settings.setDocs(docs)
- @saveBtn.textContent = if app.appCache then 'Downloading\u2026' else 'Saving\u2026'
+ @saveBtn.textContent = 'Saving\u2026'
disabledDocs = new app.collections.Docs(doc for doc in app.docs.all() when docs.indexOf(doc.slug) is -1)
disabledDocs.uninstall ->
app.db.migrate()
@@ -83,9 +81,3 @@ class app.views.Settings extends app.View
$.stopEvent(event)
app.router.show '/'
return
-
- onAppCacheProgress: (event) =>
- if event.lengthComputable
- percentage = Math.round event.loaded * 100 / event.total
- @saveBtn.textContent = "Downloading\u2026 (#{percentage}%)"
- return
diff --git a/assets/javascripts/views/search/search.coffee b/assets/javascripts/views/search/search.coffee
index 8fab885c..7d05f0a0 100644
--- a/assets/javascripts/views/search/search.coffee
+++ b/assets/javascripts/views/search/search.coffee
@@ -30,6 +30,9 @@ class app.views.Search extends app.View
.on 'results', @onResults
.on 'end', @onEnd
+ @scope
+ .on 'change', @onScopeChange
+
app.on 'ready', @onReady
$.on window, 'hashchange', @searchUrl
$.on window, 'focus', @onWindowFocus
@@ -138,6 +141,11 @@ class app.views.Search extends app.View
$.stopEvent(event)
return
+ onScopeChange: =>
+ @value = ''
+ @onInput()
+ return
+
afterRoute: (name, context) =>
return if app.shortcuts.eventInProgress?.name is 'escape'
@reset(true) if not context.init and app.router.isIndex()
diff --git a/assets/javascripts/views/search/search_scope.coffee b/assets/javascripts/views/search/search_scope.coffee
index 24de57ce..52ff753a 100644
--- a/assets/javascripts/views/search/search_scope.coffee
+++ b/assets/javascripts/views/search/search_scope.coffee
@@ -6,7 +6,9 @@ class app.views.SearchScope extends app.View
tag: '._search-tag'
@events:
+ click: 'onClick'
keydown: 'onKeydown'
+ textInput: 'onTextInput'
@routes:
after: 'afterRoute'
@@ -87,17 +89,33 @@ class app.views.SearchScope extends app.View
@trigger 'change', null, previousDoc
return
+ doScopeSearch: (event) =>
+ @search @input.value[0...@input.selectionStart]
+ $.stopEvent(event) if @doc
+ return
+
+ onClick: (event) =>
+ if event.target is @tag
+ @reset()
+ $.stopEvent(event)
+ return
+
onKeydown: (event) =>
if event.which is 8 # backspace
- if @doc and not @input.value
- $.stopEvent(event)
+ if @doc and @input.selectionEnd is 0
@reset()
- else if not @doc and @input.value
+ $.stopEvent(event)
+ else if not @doc and @input.value and not $.isChromeForAndroid()
return if event.ctrlKey or event.metaKey or event.altKey or event.shiftKey
if event.which is 9 or # tab
(event.which is 32 and app.isMobile()) # space
- @search @input.value[0...@input.selectionStart]
- $.stopEvent(event) if @doc
+ @doScopeSearch(event)
+ return
+
+ onTextInput: (event) =>
+ return unless $.isChromeForAndroid()
+ if not @doc and @input.value and event.data == ' '
+ @doScopeSearch(event)
return
extractHashValue: ->
diff --git a/assets/javascripts/views/sidebar/sidebar.coffee b/assets/javascripts/views/sidebar/sidebar.coffee
index c8dc52a6..f3ae3bd4 100644
--- a/assets/javascripts/views/sidebar/sidebar.coffee
+++ b/assets/javascripts/views/sidebar/sidebar.coffee
@@ -28,7 +28,7 @@ class app.views.Sidebar extends app.View
app.on 'ready', @onReady
- $.on document.documentElement, 'mouseleave', (event) => @display() if event.clientX < 10
+ $.on document.documentElement, 'mouseleave', (event) => @display() unless event.clientX <= 0
$.on document.documentElement, 'mouseenter', => @resetDisplay(forceNoHover: false)
return
diff --git a/assets/stylesheets/application.css.scss b/assets/stylesheets/application.css.scss
index 2a64e5c9..85d1134f 100644
--- a/assets/stylesheets/application.css.scss
+++ b/assets/stylesheets/application.css.scss
@@ -1,7 +1,6 @@
-//= depend_on docs-1.png
-//= depend_on docs-1@2x.png
-//= depend_on docs-2.png
-//= depend_on docs-2@2x.png
+//= depend_on sprites/docs.png
+//= depend_on sprites/docs@2x.png
+//= depend_on sprites/docs.json
/*!
* Copyright 2013-2019 Thibaut Courouble and other contributors
diff --git a/assets/stylesheets/components/_header.scss b/assets/stylesheets/components/_header.scss
index 5bae8901..e74830aa 100644
--- a/assets/stylesheets/components/_header.scss
+++ b/assets/stylesheets/components/_header.scss
@@ -215,5 +215,6 @@
color: var(--textColorLight);
background: var(--searchTagBackground);
border-radius: 2px;
+ cursor: pointer;
@extend %truncate-text;
}
diff --git a/assets/stylesheets/components/_notif.scss b/assets/stylesheets/components/_notif.scss
index dd23c43a..f0880fdd 100644
--- a/assets/stylesheets/components/_notif.scss
+++ b/assets/stylesheets/components/_notif.scss
@@ -134,3 +134,7 @@
._notif-info { color: var(--textColorLight); }
}
+
+._notif-right {
+ float: right;
+}
diff --git a/assets/stylesheets/global/_icons.scss b/assets/stylesheets/global/_icons.scss
deleted file mode 100644
index e7a805f4..00000000
--- a/assets/stylesheets/global/_icons.scss
+++ /dev/null
@@ -1,182 +0,0 @@
-%svg-icon {
- display: inline-block;
- vertical-align: top;
- width: 1rem;
- height: 1rem;
- pointer-events: none;
- fill: currentColor;
-}
-
-%doc-icon {
- content: '';
- display: block;
- width: 1rem;
- height: 1rem;
- background-image: image-url('docs-1.png');
- background-size: 10rem 10rem;
-}
-
-%doc-icon-2 { background-image: image-url('docs-2.png') !important; }
-
-@media (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 144dpi) {
- %doc-icon { background-image: image-url('docs-1@2x.png'); }
- %doc-icon-2 { background-image: image-url('docs-2@2x.png') !important; }
-}
-
-html._theme-dark {
- %darkIconFix {
- filter: invert(100%) grayscale(100%);
- -webkit-filter: invert(100%) grayscale(100%);
- }
-}
-
-._icon-jest:before { background-position: 0 0; }
-._icon-liquid:before { background-position: -1rem 0; }
-._icon-openjdk:before { background-position: -2rem 0; }
-._icon-codeceptjs:before { background-position: -3rem 0; }
-._icon-codeception:before { background-position: -4rem 0; }
-._icon-sqlite:before { background-position: -5rem 0; @extend %darkIconFix !optional; }
-._icon-async:before { background-position: -6rem 0; @extend %darkIconFix !optional; }
-._icon-http:before { background-position: -7rem 0; @extend %darkIconFix !optional; }
-._icon-jquery:before { background-position: -8rem 0; @extend %darkIconFix !optional; }
-._icon-underscore:before { background-position: -9rem 0; @extend %darkIconFix !optional; }
-._icon-html:before { background-position: 0 -1rem; }
-._icon-css:before { background-position: -1rem -1rem; }
-._icon-dom:before { background-position: -2rem -1rem; }
-._icon-dom_events:before { background-position: -3rem -1rem; }
-._icon-javascript:before { background-position: -4rem -1rem; }
-._icon-backbone:before { background-position: -5rem -1rem; @extend %darkIconFix !optional; }
-._icon-node:before,
-._icon-node_lts:before { background-position: -6rem -1rem; }
-._icon-sass:before { background-position: -7rem -1rem; }
-._icon-less:before { background-position: -8rem -1rem; }
-._icon-angularjs:before { background-position: -9rem -1rem; }
-._icon-coffeescript:before { background-position: 0 -2rem; @extend %darkIconFix !optional; }
-._icon-ember:before { background-position: -1rem -2rem; }
-._icon-yarn:before { background-position: -2rem -2rem; }
-._icon-immutable:before { background-position: -3rem -2rem; @extend %darkIconFix !optional; }
-._icon-jqueryui:before { background-position: -4rem -2rem; }
-._icon-jquerymobile:before { background-position: -5rem -2rem; }
-._icon-lodash:before { background-position: -6rem -2rem; }
-._icon-php:before { background-position: -7rem -2rem; }
-._icon-ruby:before,
-._icon-minitest:before { background-position: -8rem -2rem; }
-._icon-rails:before { background-position: -9rem -2rem; }
-._icon-python:before,
-._icon-python2:before { background-position: 0 -3rem; }
-._icon-git:before { background-position: -1rem -3rem; }
-._icon-redis:before { background-position: -2rem -3rem; }
-._icon-postgresql:before { background-position: -3rem -3rem; }
-._icon-d3:before { background-position: -4rem -3rem; }
-._icon-knockout:before { background-position: -5rem -3rem; }
-._icon-moment:before { background-position: -6rem -3rem; @extend %darkIconFix !optional; }
-._icon-c:before { background-position: -7rem -3rem; }
-._icon-statsmodels:before { background-position: -8rem -3rem; }
-._icon-yii:before,
-._icon-yii1:before { background-position: -9rem -3rem; }
-._icon-cpp:before { background-position: 0 -4rem; }
-._icon-go:before { background-position: -1rem -4rem; }
-._icon-express:before { background-position: -2rem -4rem; }
-._icon-grunt:before { background-position: -3rem -4rem; }
-._icon-rust:before { background-position: -4rem -4rem; @extend %darkIconFix !optional; }
-._icon-laravel:before { background-position: -5rem -4rem; }
-._icon-haskell:before { background-position: -6rem -4rem; }
-._icon-requirejs:before { background-position: -7rem -4rem; }
-._icon-chai:before { background-position: -8rem -4rem; }
-._icon-sinon:before { background-position: -9rem -4rem; }
-._icon-cordova:before { background-position: 0 -5rem; }
-._icon-markdown:before { background-position: -1rem -5rem; @extend %darkIconFix !optional; }
-._icon-django:before { background-position: -2rem -5rem; }
-._icon-xslt_xpath:before { background-position: -3rem -5rem; }
-._icon-nginx:before,
-._icon-nginx_lua_module:before { background-position: -4rem -5rem; }
-._icon-svg:before { background-position: -5rem -5rem; }
-._icon-marionette:before { background-position: -6rem -5rem; }
-._icon-jsdoc:before,
-._icon-koa:before,
-._icon-graphite:before,
-._icon-mongoose:before { background-position: -7rem -5rem; }
-._icon-phpunit:before { background-position: -8rem -5rem; }
-._icon-nokogiri:before { background-position: -9rem -5rem; @extend %darkIconFix !optional; }
-._icon-rethinkdb:before { background-position: 0 -6rem; }
-._icon-react:before { background-position: -1rem -6rem; }
-._icon-socketio:before { background-position: -2rem -6rem; }
-._icon-modernizr:before { background-position: -3rem -6rem; }
-._icon-bower:before { background-position: -4rem -6rem; }
-._icon-fish:before { background-position: -5rem -6rem; @extend %darkIconFix !optional; }
-._icon-scikit_image:before { background-position: -6rem -6rem; }
-._icon-twig:before { background-position: -7rem -6rem; }
-._icon-pandas:before { background-position: -8rem -6rem; }
-._icon-scikit_learn:before { background-position: -9rem -6rem; }
-._icon-bottle:before { background-position: 0 -7rem; }
-._icon-docker:before { background-position: -1rem -7rem; }
-._icon-cakephp:before { background-position: -2rem -7rem; }
-._icon-lua:before { background-position: -3rem -7rem; @extend %darkIconFix !optional; }
-._icon-clojure:before { background-position: -4rem -7rem; }
-._icon-symfony:before { background-position: -5rem -7rem; }
-._icon-mocha:before { background-position: -6rem -7rem; }
-._icon-meteor:before { background-position: -7rem -7rem; @extend %darkIconFix !optional; }
-._icon-npm:before { background-position: -8rem -7rem; }
-._icon-apache_http_server:before { background-position: -9rem -7rem; }
-._icon-drupal:before { background-position: 0 -8rem; }
-._icon-webpack:before { background-position: -1rem -8rem; }
-._icon-phaser:before { background-position: -2rem -8rem; }
-._icon-vue:before { background-position: -3rem -8rem; }
-._icon-opentsdb:before { background-position: -4rem -8rem; }
-._icon-q:before { background-position: -5rem -8rem; }
-._icon-crystal:before { background-position: -6rem -8rem; @extend %darkIconFix !optional; }
-._icon-julia:before { background-position: -7rem -8rem; @extend %darkIconFix !optional; }
-._icon-redux:before { background-position: -8rem -8rem; @extend %darkIconFix !optional; }
-._icon-bootstrap:before { background-position: -9rem -8rem; }
-._icon-react_native:before { background-position: 0 -9rem; }
-._icon-phalcon:before { background-position: -1rem -9rem; }
-._icon-matplotlib:before { background-position: -2rem -9rem; }
-._icon-cmake:before { background-position: -3rem -9rem; }
-._icon-elixir:before { background-position: -4rem -9rem; @extend %darkIconFix !optional; }
-._icon-vagrant:before { background-position: -5rem -9rem; }
-._icon-dojo:before { background-position: -6rem -9rem; }
-._icon-flow:before { background-position: -7rem -9rem; }
-._icon-relay:before { background-position: -8rem -9rem; }
-._icon-phoenix:before { background-position: -9rem -9rem; }
-
-._icon-tcl_tk:before { background-position: 0 0; @extend %doc-icon-2; }
-._icon-erlang:before { background-position: -1rem 0; @extend %doc-icon-2; }
-._icon-chef:before { background-position: -2rem 0; @extend %doc-icon-2; }
-._icon-ramda:before { background-position: -3rem 0; @extend %doc-icon-2; @extend %darkIconFix !optional; }
-._icon-codeigniter:before { background-position: -4rem 0; @extend %doc-icon-2; @extend %darkIconFix !optional; }
-._icon-influxdata:before { background-position: -5rem 0; @extend %doc-icon-2; @extend %darkIconFix !optional; }
-._icon-tensorflow:before { background-position: -6rem 0; @extend %doc-icon-2; }
-._icon-haxe:before { background-position: -7rem 0; @extend %doc-icon-2; }
-._icon-ansible:before { background-position: -8rem 0; @extend %doc-icon-2; @extend %darkIconFix !optional; }
-._icon-typescript:before { background-position: -9rem 0; @extend %doc-icon-2; }
-._icon-browser_support_tables:before { background-position: 0rem -1rem; @extend %doc-icon-2; }
-._icon-gnu_fortran:before { background-position: -1rem -1rem; @extend %doc-icon-2; }
-._icon-gcc:before { background-position: -2rem -1rem; @extend %doc-icon-2; }
-._icon-perl:before { background-position: -3rem -1rem; @extend %doc-icon-2; }
-._icon-apache_pig:before { background-position: -4rem -1rem; @extend %doc-icon-2; }
-._icon-numpy:before { background-position: -5rem -1rem; @extend %doc-icon-2; }
-._icon-kotlin:before { background-position: -6rem -1rem; @extend %doc-icon-2; }
-._icon-padrino:before { background-position: -7rem -1rem; @extend %doc-icon-2; }
-._icon-angular:before { background-position: -8rem -1rem; @extend %doc-icon-2; }
-._icon-love:before { background-position: -9rem -1rem; @extend %doc-icon-2; }
-._icon-jasmine:before { background-position: 0 -2rem; @extend %doc-icon-2; }
-._icon-pug:before { background-position: -1rem -2rem; @extend %doc-icon-2; }
-._icon-electron:before { background-position: -2rem -2rem; @extend %doc-icon-2; }
-._icon-falcon:before { background-position: -3rem -2rem; @extend %doc-icon-2; }
-._icon-godot:before { background-position: -4rem -2rem; @extend %doc-icon-2; }
-._icon-nim:before { background-position: -5rem -2rem; @extend %doc-icon-2; @extend %darkIconFix !optional; }
-._icon-vulkan:before { background-position: -6rem -2rem; @extend %doc-icon-2; @extend %darkIconFix !optional; }
-._icon-d:before { background-position: -7rem -2rem; @extend %doc-icon-2; }
-._icon-bluebird:before { background-position: -8rem -2rem; @extend %doc-icon-2; }
-._icon-eslint:before { background-position: -9rem -2rem; @extend %doc-icon-2; }
-._icon-homebrew:before { background-position: 0 -3rem; @extend %doc-icon-2; }
-._icon-jekyll:before { background-position: -1rem -3rem; @extend %doc-icon-2; }
-._icon-babel:before { background-position: -2rem -3rem; @extend %doc-icon-2; }
-._icon-leaflet:before { background-position: -3rem -3rem; @extend %doc-icon-2; }
-._icon-terraform:before { background-position: -4rem -3rem; @extend %doc-icon-2; }
-._icon-pygame:before { background-position: -5rem -3rem; @extend %doc-icon-2; }
-._icon-bash:before { background-position: -6rem -3rem; @extend %doc-icon-2; }
-._icon-dart:before { background-position: -7rem -3rem; @extend %doc-icon-2; }
-._icon-qt:before { background-position: -8rem -3rem; @extend %doc-icon-2; }
-._icon-puppeteer:before { background-position: -9rem -3rem; @extend %doc-icon-2; }
-._icon-handlebars:before { background-position: 0 -4rem; @extend %doc-icon-2; @extend %darkIconFix !optional; }
diff --git a/assets/stylesheets/global/_icons.scss.erb b/assets/stylesheets/global/_icons.scss.erb
new file mode 100644
index 00000000..b2b22c22
--- /dev/null
+++ b/assets/stylesheets/global/_icons.scss.erb
@@ -0,0 +1,43 @@
+<% manifest = JSON.parse(File.read('assets/images/sprites/docs.json')) %>
+
+%svg-icon {
+ display: inline-block;
+ vertical-align: top;
+ width: 1rem;
+ height: 1rem;
+ pointer-events: none;
+ fill: currentColor;
+}
+
+%doc-icon {
+ content: '';
+ display: block;
+ width: 1rem;
+ height: 1rem;
+ background-image: image-url('sprites/docs.png');
+ background-size: <%= manifest['icons_per_row'] %>rem <%= manifest['icons_per_row'] %>rem;
+}
+
+@media (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 144dpi) {
+ %doc-icon { background-image: image-url('sprites/docs@2x.png'); }
+}
+
+html._theme-dark {
+ %darkIconFix {
+ filter: invert(100%) grayscale(100%);
+ -webkit-filter: invert(100%) grayscale(100%);
+ }
+}
+
+<%=
+ items = []
+
+ manifest['items'].each do |item|
+ rules = []
+ rules << "background-position: -#{item['col']}rem -#{item['row']}rem;"
+ rules << "@extend %darkIconFix !optional;" if item['dark_icon_fix']
+ items << "._icon-#{item['type']}:before { #{rules.join(' ')} }"
+ end
+
+ items.join('')
+ %>
diff --git a/docs/adding-docs.md b/docs/adding-docs.md
index 03c6b87a..9984a15c 100644
--- a/docs/adding-docs.md
+++ b/docs/adding-docs.md
@@ -1,6 +1,6 @@
Adding a documentation may look like a daunting task but once you get the hang of it, it's actually quite simple. Don't hesitate to ask for help [in Gitter](https://gitter.im/FreeCodeCamp/DevDocs) if you ever get stuck.
-**Note:** please read the [contributing guidelines](https://github.com/Thibaut/devdocs/blob/master/.github/CONTRIBUTING.md) before submitting a new documentation.
+**Note:** please read the [contributing guidelines](../.github/CONTRIBUTING.md) before submitting a new documentation.
1. Create a subclass of `Docs::UrlScraper` or `Docs::FileScraper` in the `lib/docs/scrapers/` directory. Its name should be the [PascalCase](http://api.rubyonrails.org/classes/String.html#method-i-camelize) equivalent of the filename (e.g. `my_doc` → `MyDoc`)
2. Add the appropriate class attributes and filter options (see the [Scraper Reference](./scraper-reference.md) page).
@@ -13,9 +13,11 @@ Adding a documentation may look like a daunting task but once you get the hang o
6. Generate the full documentation using the `thor docs:generate [my_doc] --force` command. Additionally, you can use the `--verbose` option to see which files are being created/updated/deleted (useful to see what changed since the last run), and the `--debug` option to see which URLs are being requested and added to the queue (useful to pin down which page adds unwanted URLs to the queue).
7. Start the server, open the app, enable the documentation, and see how everything plays out.
8. Tweak the scraper/filters and repeat 5) and 6) until the pages and metadata are ok.
-9. To customize the pages' styling, create an SCSS file in the `assets/stylesheets/pages/` directory and import it in both `application.css.scss` AND `application-dark.css.scss`. Both the file and CSS class should be named `_[type]` where [type] is equal to the scraper's `type` attribute (documentations with the same type share the same custom CSS and JS). _(Note: feel free to submit a pull request without custom CSS/JS)_
+9. To customize the pages' styling, create an SCSS file in the `assets/stylesheets/pages/` directory and import it in both `application.css.scss` AND `application-dark.css.scss`. Both the file and CSS class should be named `_[type]` where [type] is equal to the scraper's `type` attribute (documentations with the same type share the same custom CSS and JS). Setting the type to `simple` will apply the general styling rules in `assets/stylesheets/pages/_simple.scss`, which can be used for documentations where little to no CSS changes are needed.
10. To add syntax highlighting or execute custom JavaScript on the pages, create a file in the `assets/javascripts/views/pages/` directory (take a look at the other files to see how it works).
-11. Add the documentation's icon in the `public/icons/docs/[my_doc]/` directory, in both 16x16 and 32x32-pixels formats. It'll be added to the icon sprite after your pull request is merged.
+11. Add the documentation's icon in the `public/icons/docs/[my_doc]/` directory, in both 16x16 and 32x32-pixels formats. The icon spritesheet is automatically generated when you (re)start your local DevDocs instance.
+12. Add the documentation's copyright details to the list in `assets/javascripts/templates/pages/about_tmpl.coffee`. This is the data shown in the table on the [about](https://devdocs.io/about) page, and is ordered alphabetically. Simply copying an existing item, placing it in the right slot and updating the values to match the new scraper will do the job.
+13. Ensure `thor updates:check [my_doc]` shows the correct latest version.
If the documentation includes more than a few hundreds pages and is available for download, try to scrape it locally (e.g. using `FileScraper`). It'll make the development process much faster and avoids putting too much load on the source site. (It's not a problem if your scraper is coupled to your local setup, just explain how it works in your pull request.)
diff --git a/docs/Filter-Reference.md b/docs/filter-reference.md
similarity index 100%
rename from docs/Filter-Reference.md
rename to docs/filter-reference.md
diff --git a/docs/maintainers.md b/docs/maintainers.md
index d994a0fd..da7e910e 100644
--- a/docs/maintainers.md
+++ b/docs/maintainers.md
@@ -4,7 +4,7 @@ This document is intended for [DevDocs maintainers](#list-of-maintainers).
## Merging pull requests
-- Unless the change is trivial or in an area that you are familiar with, PRs should be approved by at least two maintainers before being merged.
+- PRs should be approved by at least one maintainer before being merged.
- PRs that add or update documentations should always be merged locally, and the app deployed, before the merge is pushed to GitHub.
@@ -21,8 +21,7 @@ The process for updating docs is as follow:
- Commit the changes (protip: use the `thor docs:commit` command documented below).
- Optional: do more updates.
- Run `thor docs:upload` (documented below).
-- [Deploy the app](#deploying-devdocs) and verify that everything works in production.
-- Push to GitHub.
+- Push to GitHub to [deploy the app](#deploying-devdocs) and verify that everything works in production.
- Run `thor docs:clean` (documented below).
Note: changes to `public/docs/docs.json` should never be committed. This file reflects which documentations have been downloaded or generated locally, which is always none on a fresh `git clone`.
@@ -82,21 +81,22 @@ In addition to the [publicly-documented commands](https://github.com/freeCodeCam
## Deploying DevDocs
-Once docs have been uploaded via `thor docs:upload` (if applicable), deploying DevDocs is as simple as running `git push heroku master`. See [Heroku's documentation](https://devcenter.heroku.com/articles/git) for more information.
+Once docs have been uploaded via `thor docs:upload` (if applicable), you can push to the DevDocs master branch (or merge the PR containing the updates). If the Travis build succeeds, the Heroku application will be deployed automatically.
-- If you're deploying documentation updates, verify that the documentations work properly once the deploy is done (you will need to reload [devdocs.io](https://devdocs.io/) a couple times for the application cache to update and the new version to load).
+- If you're deploying documentation updates, verify that the documentations work properly once the deploy is done. Keep in mind that you'll need to wait a few seconds for the service worker to finish caching the new assets. You should see a "DevDocs has been updated" notification appear when the caching is done, after which you need to refresh the page to see the changes.
- If you're deploying frontend changes, monitor [Sentry](https://sentry.io/devdocs/devdocs-js/) for new JS errors once the deploy is done.
- If you're deploying server changes, monitor New Relic (accessible through [the Heroku dashboard](https://dashboard.heroku.com/apps/devdocs)) for Ruby exceptions and throughput or response time changes once the deploy is done.
-If any issue arises, run `heroku rollback` to rollback to the previous of the app (this can also be done via Heroku's UI). Note that this will not revert changes made to documentation files that were uploaded via `thor docs:upload`. Try and fix the issue as quickly as possible, then re-deploy the app. Reach out to other maintainers if you need help.
+If any issue arises, run `heroku rollback` to rollback to the previous version of the app (this can also be done via Heroku's UI). Note that this will not revert changes made to documentation files that were uploaded via `thor docs:upload`. Try and fix the issue as quickly as possible, then re-deploy the app. Reach out to other maintainers if you need help.
If this is your first deploy, make sure another maintainer is around to assist.
## List of maintainers
-- [Beau Carnes](https://github.com/beaucarnes)
- [Jed Fox](https://github.com/j-f1)
- [Jasper van Merle](https://github.com/jmerle)
+- [Ahmad Abdolsaheb](https://github.com/ahmadabdolsaheb)
+- [Mrugesh Mohapatra](https://github.com/raisedadead)
- [Thibaut Courouble](https://github.com/thibaut)
Interested in helping maintain DevDocs? Come talk to us on [Gitter](https://gitter.im/FreeCodeCamp/DevDocs) :)
diff --git a/docs/Scraper-Reference.md b/docs/scraper-reference.md
similarity index 86%
rename from docs/Scraper-Reference.md
rename to docs/scraper-reference.md
index d9fe8b4a..c2872388 100644
--- a/docs/Scraper-Reference.md
+++ b/docs/scraper-reference.md
@@ -184,3 +184,44 @@ More information about how filters work is available on the [Filter Reference](.
Overrides the `:title` option for the root page only.
_Note: this filter is disabled by default._
+
+## Keeping scrapers up-to-date
+
+In order to keep scrapers up-to-date the `get_latest_version(opts)` method should be overridden. If `self.release` is defined, this should return the latest version of the documentation. If `self.release` is not defined, it should return the Epoch time when the documentation was last modified. If the documentation will never change, simply return `1.0.0`. The result of this method is periodically reported in a "Documentation versions report" issue which helps maintainers keep track of outdated documentations.
+
+To make life easier, there are a few utility methods that you can use in `get_latest_version`:
+* `fetch(url, opts)`
+
+ Makes a GET request to the url and returns the response body.
+
+ Example: [lib/docs/scrapers/bash.rb](../lib/docs/scrapers/bash.rb)
+* `fetch_doc(url, opts)`
+
+ Makes a GET request to the url and returns the HTML body converted to a Nokogiri document.
+
+ Example: [lib/docs/scrapers/git.rb](../lib/docs/scrapers/git.rb)
+* `fetch_json(url, opts)`
+
+ Makes a GET request to the url and returns the JSON body converted to a dictionary.
+
+ Example: [lib/docs/scrapers/mdn/mdn.rb](../lib/docs/scrapers/mdn/mdn.rb)
+* `get_npm_version(package, opts)`
+
+ Returns the latest version of the given npm package.
+
+ Example: [lib/docs/scrapers/bower.rb](../lib/docs/scrapers/bower.rb)
+* `get_latest_github_release(owner, repo, opts)`
+
+ Returns the tag name of the latest GitHub release of the given repository. If the tag name is preceded by a "v", the "v" will be removed.
+
+ Example: [lib/docs/scrapers/jsdoc.rb](../lib/docs/scrapers/jsdoc.rb)
+* `get_github_tags(owner, repo, opts)`
+
+ Returns the list of tags on the given repository ([format](https://developer.github.com/v3/repos/#list-tags)).
+
+ Example: [lib/docs/scrapers/liquid.rb](../lib/docs/scrapers/liquid.rb)
+* `get_github_file_contents(owner, repo, path, opts)`
+
+ Returns the contents of the requested file in the default branch of the given repository.
+
+ Example: [lib/docs/scrapers/minitest.rb](../lib/docs/scrapers/minitest.rb)
diff --git a/lib/app.rb b/lib/app.rb
index 32cac31b..a1ace892 100644
--- a/lib/app.rb
+++ b/lib/app.rb
@@ -37,6 +37,9 @@ class App < Sinatra::Application
set :csp, false
+ require 'docs'
+ Docs.generate_manifest
+
Dir[docs_path, root.join(assets_prefix, '*/')].each do |path|
sprockets.append_path(path)
end
@@ -50,6 +53,11 @@ class App < Sinatra::Application
end
configure :test, :development do
+ require 'thor'
+ load 'tasks/sprites.thor'
+
+ SpritesCLI.new.invoke(:generate)
+
require 'active_support/per_thread_registry'
require 'active_support/cache'
sprockets.cache = ActiveSupport::Cache.lookup_store :file_store, root.join('tmp', 'cache', 'assets', environment.to_s)
@@ -192,35 +200,45 @@ class App < Sinatra::Application
request.query_string.empty? ? nil : "?#{request.query_string}"
end
- def manifest_asset_urls
- @@manifest_asset_urls ||= [
+ def service_worker_asset_urls
+ @@service_worker_asset_urls ||= [
javascript_path('application', asset_host: false),
stylesheet_path('application'),
- image_path('docs-1.png'),
- image_path('docs-1@2x.png'),
- image_path('docs-2.png'),
- image_path('docs-2@2x.png'),
- asset_path('docs.js')
- ]
+ image_path('sprites/docs.png'),
+ image_path('sprites/docs@2x.png'),
+ asset_path('docs.js'),
+ App.production? ? nil : javascript_path('debug'),
+ ].compact
end
- def app_size
- @app_size ||= memoized_cookies['size'].nil? ? '20rem' : "#{memoized_cookies['size']}px"
- end
+ # Returns a cache name for the service worker to use which changes if any of the assets changes
+ # When a manifest exist, this name is only created once based on the asset manifest because it never changes without a server restart
+ # If a manifest does not exist, it is created every time this method is called because the assets can change while the server is running
+ def service_worker_cache_name
+ if File.exist?(App.assets_manifest_path)
+ if defined?(@@service_worker_cache_name)
+ return @@service_worker_cache_name
+ end
- def app_layout
- memoized_cookies['layout']
- end
+ digest = Sprockets::Manifest
+ .new(nil, App.assets_manifest_path)
+ .files
+ .values
+ .map {|file| file["digest"]}
+ .join
- def app_theme
- @app_theme ||= memoized_cookies['dark'].nil? ? 'default' : 'dark'
- end
+ return @@service_worker_cache_name ||= Digest::MD5.hexdigest(digest)
+ else
+ paths = App.sprockets
+ .each_file
+ .to_a
+ .reject {|file| file.start_with?(App.docs_path)}
- def dark_theme?
- app_theme == 'dark'
+ return App.sprockets.pack_hexdigest(App.sprockets.files_digest(paths))
+ end
end
- def redirect_via_js(path) # courtesy of HTML5 App Cache
+ def redirect_via_js(path)
response.set_cookie :initial_path, value: path, expires: Time.now + 15, path: '/'
redirect '/', 302
end
@@ -243,15 +261,15 @@ class App < Sinatra::Application
end
end
- get '/manifest.appcache' do
- content_type 'text/cache-manifest'
+ get '/service-worker.js' do
+ content_type 'application/javascript'
expires 0, :'no-cache'
- erb :manifest
+ erb :'service-worker.js'
end
get '/' do
return redirect "/#q=#{params[:q]}" if params[:q]
- return redirect '/' unless request.query_string.empty? # courtesy of HTML5 App Cache
+ return redirect '/' unless request.query_string.empty?
response.headers['Content-Security-Policy'] = settings.csp if settings.csp
erb :index
end
diff --git a/lib/docs/core/doc.rb b/lib/docs/core/doc.rb
index cb1cd209..da21daf8 100644
--- a/lib/docs/core/doc.rb
+++ b/lib/docs/core/doc.rb
@@ -152,7 +152,6 @@ module Docs
end
end
-
def initialize
raise NotImplementedError, "#{self.class} is an abstract class and cannot be instantiated." if self.class.abstract
end
@@ -164,5 +163,104 @@ module Docs
def build_pages(&block)
raise NotImplementedError
end
+
+ def get_scraper_version(opts)
+ if self.class.method_defined?(:options) and !options[:release].nil?
+ options[:release]
+ else
+ # If options[:release] does not exist, we return the Epoch timestamp of when the doc was last modified in DevDocs production
+ json = fetch_json('https://devdocs.io/docs.json', opts)
+ items = json.select {|item| item['name'] == self.class.name}
+ items = items.map {|item| item['mtime']}
+ items.max
+ end
+ end
+
+ # Should return the latest version of this documentation
+ # If options[:release] is defined, it should be in the same format
+ # If options[:release] is not defined, it should return the Epoch timestamp of when the documentation was last updated
+ # If the docs will never change, simply return '1.0.0'
+ def get_latest_version(opts)
+ raise NotImplementedError
+ end
+
+ # Returns whether or not this scraper is outdated.
+ #
+ # The default implementation assumes the documentation uses a semver(-like) approach when it comes to versions.
+ # Patch updates are ignored because there are usually little to no documentation changes in bug-fix-only releases.
+ #
+ # Scrapers of documentations that do not use this versioning approach should override this method.
+ #
+ # Examples of the default implementation:
+ # 1 -> 2 = outdated
+ # 1.1 -> 1.2 = outdated
+ # 1.1.1 -> 1.1.2 = not outdated
+ def is_outdated(scraper_version, latest_version)
+ scraper_parts = scraper_version.to_s.split(/\./).map(&:to_i)
+ latest_parts = latest_version.to_s.split(/\./).map(&:to_i)
+
+ # Only check the first two parts, the third part is for patch updates
+ [0, 1].each do |i|
+ break if i >= scraper_parts.length or i >= latest_parts.length
+ return true if latest_parts[i] > scraper_parts[i]
+ return false if latest_parts[i] < scraper_parts[i]
+ end
+
+ false
+ end
+
+ private
+
+ #
+ # Utility methods for get_latest_version
+ #
+
+ def fetch(url, opts)
+ headers = {}
+
+ if opts.key?(:github_token) and url.start_with?('https://api.github.com/')
+ headers['Authorization'] = "token #{opts[:github_token]}"
+ end
+
+ opts[:logger].debug("Fetching #{url}")
+ response = Request.run(url, { connecttimeout: 15, headers: headers })
+
+ if response.success?
+ response.body
+ else
+ reason = response.timed_out? ? "Timed out while connecting to #{url}" : "Couldn't fetch #{url} (response code #{response.code})"
+ opts[:logger].error(reason)
+ raise reason
+ end
+ end
+
+ def fetch_doc(url, opts)
+ body = fetch(url, opts)
+ Nokogiri::HTML.parse(body, nil, 'UTF-8')
+ end
+
+ def fetch_json(url, opts)
+ JSON.parse fetch(url, opts)
+ end
+
+ def get_npm_version(package, opts)
+ json = fetch_json("https://registry.npmjs.com/#{package}", opts)
+ json['dist-tags']['latest']
+ end
+
+ def get_latest_github_release(owner, repo, opts)
+ release = fetch_json("https://api.github.com/repos/#{owner}/#{repo}/releases/latest", opts)
+ tag_name = release['tag_name']
+ tag_name.start_with?('v') ? tag_name[1..-1] : tag_name
+ end
+
+ def get_github_tags(owner, repo, opts)
+ fetch_json("https://api.github.com/repos/#{owner}/#{repo}/tags", opts)
+ end
+
+ def get_github_file_contents(owner, repo, path, opts)
+ json = fetch_json("https://api.github.com/repos/#{owner}/#{repo}/contents/#{path}", opts)
+ Base64.decode64(json['content'])
+ end
end
end
diff --git a/lib/docs/core/scrapers/file_scraper.rb b/lib/docs/core/scrapers/file_scraper.rb
index 9d354631..72a99b99 100644
--- a/lib/docs/core/scrapers/file_scraper.rb
+++ b/lib/docs/core/scrapers/file_scraper.rb
@@ -29,7 +29,7 @@ module Docs
def request_one(url)
assert_source_directory_exists
- Response.new read_file(url_to_path(url)), URL.parse(url)
+ Response.new read_file(File.join(source_directory, url_to_path(url))), URL.parse(url)
end
def request_all(urls)
@@ -50,7 +50,7 @@ module Docs
end
def read_file(path)
- File.read(File.join(source_directory, path))
+ File.read(path)
rescue
instrument 'warn.doc', msg: "Failed to open file: #{path}"
nil
diff --git a/lib/docs/filters/elixir/clean_html.rb b/lib/docs/filters/elixir/clean_html.rb
index 7ff3a86a..cf703389 100644
--- a/lib/docs/filters/elixir/clean_html.rb
+++ b/lib/docs/filters/elixir/clean_html.rb
@@ -57,6 +57,11 @@ module Docs
node.parent.after(node)
end
+ css('.signature').each do |node|
+ non_text_children = node.xpath('node()[not(self::text())]')
+ non_text_children.to_a.reverse.each { |child| node.parent.add_next_sibling(child) }
+ end
+
css('pre').each do |node|
node['data-language'] = 'elixir'
node.content = node.content
diff --git a/lib/docs/scrapers/angular.rb b/lib/docs/scrapers/angular.rb
index c318ce25..3365ec67 100644
--- a/lib/docs/scrapers/angular.rb
+++ b/lib/docs/scrapers/angular.rb
@@ -155,6 +155,10 @@ module Docs
end
end
+ def get_latest_version(opts)
+ get_npm_version('@angular/core', opts)
+ end
+
private
def parse(response)
diff --git a/lib/docs/scrapers/angularjs.rb b/lib/docs/scrapers/angularjs.rb
index b8ff08b9..9d663e35 100644
--- a/lib/docs/scrapers/angularjs.rb
+++ b/lib/docs/scrapers/angularjs.rb
@@ -69,5 +69,9 @@ module Docs
self.release = '1.2.32'
self.base_url = "https://code.angularjs.org/#{release}/docs/partials/"
end
+
+ def get_latest_version(opts)
+ get_npm_version('angular', opts)
+ end
end
end
diff --git a/lib/docs/scrapers/ansible.rb b/lib/docs/scrapers/ansible.rb
index 2d62909a..b2363d4d 100644
--- a/lib/docs/scrapers/ansible.rb
+++ b/lib/docs/scrapers/ansible.rb
@@ -87,5 +87,10 @@ module Docs
quickstart.html
list_of_all_modules.html)
end
+
+ def get_latest_version(opts)
+ doc = fetch_doc('https://docs.ansible.com/ansible/latest/index.html', opts)
+ doc.at_css('.DocSiteProduct-CurrentVersion').content.strip
+ end
end
end
diff --git a/lib/docs/scrapers/apache.rb b/lib/docs/scrapers/apache.rb
index 9ee82f12..1301b574 100644
--- a/lib/docs/scrapers/apache.rb
+++ b/lib/docs/scrapers/apache.rb
@@ -33,5 +33,10 @@ module Docs
© 2018 The Apache Software Foundation
'
end
+
+ def get_latest_version(opts)
+ doc = fetch_doc('https://babeljs.io/docs/en/', opts)
+ doc.at_css('a[href="/versions"] > h3').content
+ end
end
end
diff --git a/lib/docs/scrapers/backbone.rb b/lib/docs/scrapers/backbone.rb
index b72b1084..2b33505e 100644
--- a/lib/docs/scrapers/backbone.rb
+++ b/lib/docs/scrapers/backbone.rb
@@ -20,5 +20,10 @@ module Docs
© 2010–2016 Jeremy Ashkenas, DocumentCloud#{url} " }.join
end
+ def get_latest_version(opts)
+ doc = fetch_doc('https://dojotoolkit.org/api/', opts)
+ doc.at_css('#versionSelector > option[selected]').content
+ end
+
private
def get_url_list(json, set = Set.new)
diff --git a/lib/docs/scrapers/drupal.rb b/lib/docs/scrapers/drupal.rb
index 5710eb36..3798caec 100644
--- a/lib/docs/scrapers/drupal.rb
+++ b/lib/docs/scrapers/drupal.rb
@@ -98,5 +98,10 @@ module Docs
/\A[\w\-\.]+\.php\/7\.x\z/
]
end
+
+ def get_latest_version(opts)
+ json = fetch_json('https://packagist.org/packages/drupal/drupal.json', opts)
+ json['package']['versions'].keys.find {|version| !version.end_with?('-dev')}
+ end
end
end
diff --git a/lib/docs/scrapers/electron.rb b/lib/docs/scrapers/electron.rb
index 3cb399f0..8e635f49 100644
--- a/lib/docs/scrapers/electron.rb
+++ b/lib/docs/scrapers/electron.rb
@@ -22,5 +22,10 @@ module Docs
© 2013–2018 GitHub Inc.([^<]+)<\/updated>/)[0][0]
+ DateTime.parse(timestamp).to_time.to_i
+ end
end
end
diff --git a/lib/docs/scrapers/symfony.rb b/lib/docs/scrapers/symfony.rb
index f5e4285a..4bdde054 100644
--- a/lib/docs/scrapers/symfony.rb
+++ b/lib/docs/scrapers/symfony.rb
@@ -70,5 +70,9 @@ module Docs
self.release = '2.7.35'
self.base_url = "https://api.symfony.com/#{version}/"
end
+
+ def get_latest_version(opts)
+ get_latest_github_release('symfony', 'symfony', opts)
+ end
end
end
diff --git a/lib/docs/scrapers/tcl_tk.rb b/lib/docs/scrapers/tcl_tk.rb
index 1e4b2567..bca840c6 100644
--- a/lib/docs/scrapers/tcl_tk.rb
+++ b/lib/docs/scrapers/tcl_tk.rb
@@ -25,5 +25,10 @@ module Docs
options[:attribution] = <<-HTML
Licensed under Tcl/Tk terms
HTML
+
+ def get_latest_version(opts)
+ doc = fetch_doc('https://www.tcl.tk/man/tcl/contents.htm', opts)
+ doc.at_css('h2').content.scan(/Tk([0-9.]+)/)[0][0]
+ end
end
end
diff --git a/lib/docs/scrapers/tensorflow.rb b/lib/docs/scrapers/tensorflow.rb
index 0296299f..9638b516 100644
--- a/lib/docs/scrapers/tensorflow.rb
+++ b/lib/docs/scrapers/tensorflow.rb
@@ -56,6 +56,10 @@ module Docs
/\Aextend/]
end
+ def get_latest_version(opts)
+ get_latest_github_release('tensorflow', 'tensorflow', opts)
+ end
+
private
def parse(response)
diff --git a/lib/docs/scrapers/terraform.rb b/lib/docs/scrapers/terraform.rb
index ab12775d..0965ad06 100644
--- a/lib/docs/scrapers/terraform.rb
+++ b/lib/docs/scrapers/terraform.rb
@@ -18,5 +18,10 @@ module Docs
© 2018 HashiCorp
Licensed under the MPL 2.0 License.
HTML
+
+ def get_latest_version(opts)
+ contents = get_github_file_contents('hashicorp', 'terraform-website', 'content/config.rb', opts)
+ contents.scan(/version\s+=\s+"([0-9.]+)"/)[0][0]
+ end
end
end
diff --git a/lib/docs/scrapers/twig.rb b/lib/docs/scrapers/twig.rb
index 4781dcb2..e52ff6bd 100755
--- a/lib/docs/scrapers/twig.rb
+++ b/lib/docs/scrapers/twig.rb
@@ -28,5 +28,10 @@ module Docs
self.release = '1.34.3'
self.base_url = 'https://twig.symfony.com/doc/1.x/'
end
+
+ def get_latest_version(opts)
+ tags = get_github_tags('twigphp', 'Twig', opts)
+ tags[0]['name'][1..-1]
+ end
end
end
diff --git a/lib/docs/scrapers/typescript.rb b/lib/docs/scrapers/typescript.rb
index 1117314a..777f5dd6 100644
--- a/lib/docs/scrapers/typescript.rb
+++ b/lib/docs/scrapers/typescript.rb
@@ -24,6 +24,10 @@ module Docs
© Microsoft and other contributors\n#{title} \n\n#{create_markdown_table(headings, rows)}\n "
+ end
+
+ def create_markdown_table(headings, rows)
+ header = headings.join(' | ')
+ separator = '-|' * headings.length
+ body = rows.map {|row| row.join(' | ')}
+
+ header + "\n" + separator[0...-1] + "\n" + body.join("\n")
+ end
+
+ def log_upload_success(created_issue)
+ logger.info("Successfully uploaded the results to #{created_issue['html_url']}")
+ end
+
+ #
+ # HTTP utilities
+ #
+
+ def github_get(endpoint, params = {})
+ github_request(endpoint, {method: :get, params: params})
+ end
+
+ def github_post(endpoint, params)
+ github_request(endpoint, {method: :post, body: params.to_json})
+ end
+
+ def github_patch(endpoint, params)
+ github_request(endpoint, {method: :patch, body: params.to_json})
+ end
+
+ def github_request(endpoint, opts)
+ url = "https://api.github.com#{endpoint}"
+
+ # GitHub token authentication
+ opts[:headers] = {
+ Authorization: "token #{options[:github_token]}"
+ }
+
+ # GitHub requires the Content-Type to be application/json when a body is passed
+ if opts.key?(:body)
+ opts[:headers]['Content-Type'] = 'application/json'
+ end
+
+ logger.debug("Making a #{opts[:method]} request to #{url}")
+ response = Docs::Request.run(url, opts)
+
+ # response.success? is false if the response code is 201
+ # GitHub returns 201 Created after an issue is created
+ if response.success? || response.code == 201
+ JSON.parse(response.body)
+ else
+ logger.error("Couldn't make a #{opts[:method]} request to #{url} (response code #{response.code})")
+ nil
+ end
+ end
+
+ # A utility method which ensures no progress bar is shown when stdout is not a tty
+ def with_progress_bar(&block)
+ return unless $stdout.tty?
+ @progress_bar ||= ::ProgressBar.new
+ block.call @progress_bar
+ end
+
+ def logger
+ @logger ||= Logger.new($stdout).tap do |logger|
+ logger.level = options[:verbose] ? Logger::DEBUG : Logger::INFO
+ logger.formatter = proc {|severity, datetime, progname, msg| "[#{severity}] #{msg}\n"}
+ end
+ end
+end
diff --git a/public/docs/docs.json b/public/docs/docs.json
deleted file mode 100644
index 0637a088..00000000
--- a/public/docs/docs.json
+++ /dev/null
@@ -1 +0,0 @@
-[]
\ No newline at end of file
diff --git a/public/icons/docs-1.pxm b/public/icons/docs-1.pxm
deleted file mode 100644
index d9418ee7..00000000
Binary files a/public/icons/docs-1.pxm and /dev/null differ
diff --git a/public/icons/docs-1@2x.pxm b/public/icons/docs-1@2x.pxm
deleted file mode 100644
index d2b97c84..00000000
Binary files a/public/icons/docs-1@2x.pxm and /dev/null differ
diff --git a/public/icons/docs-2.pxm b/public/icons/docs-2.pxm
deleted file mode 100644
index ba5ce1b5..00000000
Binary files a/public/icons/docs-2.pxm and /dev/null differ
diff --git a/public/icons/docs-2@2x.pxm b/public/icons/docs-2@2x.pxm
deleted file mode 100644
index 3c390953..00000000
Binary files a/public/icons/docs-2@2x.pxm and /dev/null differ
diff --git a/public/icons/docs/bluebird/16@2x.png b/public/icons/docs/bluebird/16@2x.png
index 9ffae075..64ad5903 100644
Binary files a/public/icons/docs/bluebird/16@2x.png and b/public/icons/docs/bluebird/16@2x.png differ
diff --git a/public/images/webapp-icon-192.png b/public/images/webapp-icon-192.png
new file mode 100644
index 00000000..d1d1dd75
Binary files /dev/null and b/public/images/webapp-icon-192.png differ
diff --git a/public/manifest.json b/public/manifest.json
index 1faa5978..301c56d1 100644
--- a/public/manifest.json
+++ b/public/manifest.json
@@ -4,6 +4,7 @@
"description": "API Documentation Browser",
"start_url": "/",
"display": "standalone",
+ "background_color": "#EEEEEE",
"icons": [
{
"src": "/images/webapp-icon-32.png",
@@ -25,6 +26,11 @@
"sizes": "128x128",
"type": "image/png"
},
+ {
+ "src": "/images/webapp-icon-192.png",
+ "sizes": "192x192",
+ "type": "image/png"
+ },
{
"src": "/images/webapp-icon-256.png",
"sizes": "256x256",
diff --git a/test/app_test.rb b/test/app_test.rb
index 92a24acd..8e9e369b 100644
--- a/test/app_test.rb
+++ b/test/app_test.rb
@@ -43,35 +43,6 @@ class AppTest < MiniTest::Spec
assert last_response.redirect?
assert_equal 'https://example.org/', last_response['Location']
end
-
- it "sets default size" do
- get '/'
- assert_includes last_response.body, 'data-size="20rem"'
- end
-
- it "sets size from cookie" do
- set_cookie('size=42')
- get '/'
- assert_includes last_response.body, 'data-size="42px"'
- end
-
- it "sets layout from cookie" do
- set_cookie('layout=foo')
- get '/'
- assert_includes last_response.body, ''
- end
-
- it "sets the theme from cookie" do
- get '/'
- assert_match %r{]*class="[^\"]*_theme-default}, last_response.body
- refute_includes last_response.body, '_theme-dark'
-
- set_cookie('dark=1')
-
- get '/'
- assert_match %r{]*class="[^\"]*_theme-dark}, last_response.body
- refute_includes last_response.body, '_theme-default'
- end
end
describe "/[static-page]" do
@@ -106,58 +77,6 @@ class AppTest < MiniTest::Spec
end
end
- describe "/manifest.appcache" do
- it "works" do
- get '/manifest.appcache'
- assert last_response.ok?
- end
-
- it "works with cookie" do
- set_cookie('docs=css/html~5')
- get '/manifest.appcache'
- assert last_response.ok?
- assert_includes last_response.body, '/css/index.json?1420139788'
- assert_includes last_response.body, '/html~5/index.json?1420139791'
- end
-
- it "ignores invalid docs in the cookie" do
- set_cookie('docs=foo')
- get '/manifest.appcache'
- assert last_response.ok?
- refute_includes last_response.body, 'foo'
- end
-
- it "has the word 'default' when no 'dark' cookie is set" do
- get '/manifest.appcache'
- assert_includes last_response.body, '# default'
- refute_includes last_response.body, '# dark'
- end
-
- it "has the word 'dark' when the cookie is set" do
- set_cookie('dark=1')
- get '/manifest.appcache'
- assert_includes last_response.body, '# dark'
- refute_includes last_response.body, '# default'
- end
-
- it "sets default size" do
- get '/manifest.appcache'
- assert_includes last_response.body, '20rem'
- end
-
- it "sets size from cookie" do
- set_cookie('size=42')
- get '/manifest.appcache'
- assert_includes last_response.body, '42px'
- end
-
- it "sets layout from cookie" do
- set_cookie('layout=foo_layout')
- get '/manifest.appcache'
- assert_includes last_response.body, 'foo_layout'
- end
- end
-
describe "/[doc]" do
it "renders when the doc exists and isn't enabled" do
set_cookie('docs=html~5')
diff --git a/test/lib/docs/core/scrapers/file_scraper_test.rb b/test/lib/docs/core/scrapers/file_scraper_test.rb
index 7d90d262..88b5e8d5 100644
--- a/test/lib/docs/core/scrapers/file_scraper_test.rb
+++ b/test/lib/docs/core/scrapers/file_scraper_test.rb
@@ -63,7 +63,7 @@ class FileScraperTest < MiniTest::Spec
end
it "reads a file" do
- mock(scraper).read_file(path)
+ mock(scraper).read_file(File.join(ROOT_PATH, 'docs/scraper', path))
result
end
@@ -165,7 +165,7 @@ class FileScraperTest < MiniTest::Spec
describe "#read_file" do
let :result do
- scraper.send :read_file, 'file'
+ scraper.send :read_file, File.join(ROOT_PATH, 'docs', 'scraper', 'file')
end
it "returns the file's content when the file exists in the source directory" do
diff --git a/views/app.erb b/views/app.erb
index 7cffabd0..ffaa1bf3 100644
--- a/views/app.erb
+++ b/views/app.erb
@@ -28,13 +28,7 @@
@@ -63,9 +57,3 @@
-
diff --git a/views/index.erb b/views/index.erb
index 022e927f..4fb96153 100644
--- a/views/index.erb
+++ b/views/index.erb
@@ -1,5 +1,5 @@
-
prefix="og: http://ogp.me/ns#" lang="en" class="_booting _theme-<%= app_theme %>">
+
DevDocs API Documentation
>
+
DevDocs requires JavaScript to run.
<%= erb :app -%>
<%= javascript_tag 'application', asset_host: false %>
diff --git a/views/manifest.erb b/views/manifest.erb
deleted file mode 100644
index 9d2df923..00000000
--- a/views/manifest.erb
+++ /dev/null
@@ -1,14 +0,0 @@
-CACHE MANIFEST
-# <%= app_theme %> <%= app_size %> <%= app_layout %>
-
-CACHE:
-/
-<%= manifest_asset_urls.join "\n" %>
-<%= doc_index_urls.join "\n" %>
-
-NETWORK:
-/s/
-*
-
-FALLBACK:
-/ /
diff --git a/views/other.erb b/views/other.erb
index ee9b8de1..45cab943 100644
--- a/views/other.erb
+++ b/views/other.erb
@@ -1,10 +1,11 @@
-
+
DevDocs<%= " — #{@doc['full_name']} documentation" if doc_index_page? %>
data-doc="<%= CGI::escape_html @doc.to_json %>">
+
DevDocs requires JavaScript to run.
<%= erb :app -%>
<%= javascript_tag 'application', asset_host: false %><% unless App.production? %>
diff --git a/views/service-worker.js.erb b/views/service-worker.js.erb
new file mode 100644
index 00000000..8d5698a7
--- /dev/null
+++ b/views/service-worker.js.erb
@@ -0,0 +1,49 @@
+<%# The name of the cache to store responses in %>
+<%# If the cache name changes DevDocs is assumed to be updated %>
+const cacheName = '<%= service_worker_cache_name %>';
+
+<%# Url's to cache when the service worker is installed %>
+const urlsToCache = [
+ '/',
+ '/favicon.ico',
+ '/manifest.json',
+ '<%= service_worker_asset_urls.join "',\n '" %>',
+ '<%= doc_index_urls.join "',\n '" %>',
+];
+
+<%# Set-up the cache %>
+self.addEventListener('install', event => {
+ self.skipWaiting();
+
+ event.waitUntil(
+ caches.open(cacheName).then(cache => cache.addAll(urlsToCache)),
+ );
+});
+
+<%# Remove old caches %>
+self.addEventListener('activate', event => {
+ event.waitUntil((async () => {
+ const keys = await caches.keys();
+ const jobs = keys.map(key => key !== cacheName ? caches.delete(key) : Promise.resolve());
+ return Promise.all(jobs);
+ })());
+});
+
+<%# Handle HTTP requests %>
+self.addEventListener('fetch', event => {
+ event.respondWith((async () => {
+ const cachedResponse = await caches.match(event.request);
+ if (cachedResponse) return cachedResponse;
+
+ const url = new URL(event.request.url);
+
+ <%# Attempt to return the index page from the cache if the user is visiting a url like devdocs.io/offline or devdocs.io/javascript/global_objects/array/find %>
+ <%# The index page will handle the routing %>
+ if (url.origin === location.origin && !url.pathname.includes('.')) {
+ const cachedIndex = await caches.match('/');
+ if (cachedIndex) return cachedIndex;
+ }
+
+ return fetch(event.request);
+ })());
+});
diff --git a/views/unsupported.erb b/views/unsupported.erb
index a01b7c7e..6c1ded7e 100644
--- a/views/unsupported.erb
+++ b/views/unsupported.erb
@@ -11,9 +11,9 @@
DevDocs is an API documentation browser which supports the following browsers:
Recent versions of Firefox, Chrome, or Opera
- Safari 9.1+
- Edge 16+
- iOS 10+
+ Safari 11.1+
+ Edge 17+
+ iOS 11.3+
If you're unable to upgrade, we apologize.