kitura / kitura.dev

http://www.kitura.dev

kitura.dev

This is the GitHub repository for http://www.kitura.dev, which is hosted as a GitHub pages website.

Contributing

We welcome all improvements to this website. Please see our Contributing guidelines.

Local setup

If you want to preview this website locally, follow these steps:

1. Clone the kitura.dev project onto your machine: git clone https://github.com/Kitura/kitura.dev.git
2. Enter the website directory: cd kitura.dev/website
3. Run the npm install command: npm install
4. Run the npm install -g gatsby-cli comand: npm install -g gatsby-cli
5. Run the gatsby develop command: gatsby develop

This will open the website in your default browser.

Licence

Apache Licence, Version 2.0

kitura.dev's Issues

Create a macOS guide for Getting Started

Finalise the layout/structure for the individual guides

The guides need to be written and structured in a consistent manner. To ensure this happens a structure and layout needs to be decided on.

Once this has been decided on all the guides should adhere to it. On top of that the Contributing.md should also be updated.

Create a Setting Up guide for Getting Started

/api directory in root folder, should exist under /en/ for globalisation

Jekyll-redirect-from gem installed in site and requires files to be in distinct folders. Pull request on its way.

Packages page is missing community-authored packages

https://github.com/crspybits/CredentialsDropbox
https://github.com/jacobvanorder/Kitura-CredentialsTwitter

Typo on http://ibm-swift.github.io/Kitura/Classes/Router.html

The Router class provides the external intreface for the routing of requests to the appropriate code for handling. This includes:

"interface" is misspelt.

Code sample font in index.html

I think it might look better if the code sample on the front page used a monospace font, such as IBM Plex Mono.

Create a Type-safe middleswares guide for Middlewares

Desktop-style menu bar is unsuitable for large touch-screen displays

Touch screen devices with a screen width of over 899 pixels (some tablets, especially in landscape orientation) will display the desktop-style menu bar.

This menu bar requires the user to hover over the links to access sub-menus, which isn't possible on a tablet.

Solution: clicks/taps on the menu bar items should toggle sub-menus open and closed, instead of linking directly to the first page in the sub-menu. This solution should be implemented without affecting the 'hover' functionality.

Create a Kitura CLI guide for Getting Started

Update port references to use new Kitura default of 8080

Sub-menu items on mobile menu should not display on hover

Sub-menus (the pages under Getting Started) display when a desktop/laptop user has a window with a width less than 899 pixels, and hovers over the main menu item (Getting Started). The sub-menu items disappear when no longer hovering.

This detracts from the user experience if the desktop/laptop window is small enough to initiate the mobile menu.

Create a basic webpage based on the design of #183

Once the design of #183 has been confirmed the webpage needs to be created.
This issue covers the basic elements (HTML/CSS) of the webpage.

Create a Codable Routing guide for Routing

Website still refers to ICAT

http://www.kitura.io/en/starter/deploying.html has an IBM Cloud Application Tools section, but ICAT has been retired. We should remove this section.

Sample Projects

As someone using Swift in a new way (ahem, on the server), it's useful for me to occasionally reference other Kitura apps as a way to make certain architectural decisions.

I'd love it if either here or somewhere within the IBM-Swift Github org, there was a list of open-sourced Kitura projects and tools developed by the community. I find the Kitura tutorials useful as a jumpstart, but would appreciate seeing other mature projects as well.

Ensure user selection from sidebar is highlighted

As per the design in #183 the sidebar selection the user has made should be highlighted in a dark blue, and made slightly bold.

Update guides for Swift 4

Kitura/Kitura#1156 (comment)

Create a ORM guide for Databases

Create a LoggerAPI guide for Logging

Create a Plugins guide for Databases

Create a `What is Routing?` guide for Routing

Add the ability for a user to search the documentation

As proposed in #183 it'd be useful if a user was able to search the documentation to easily find the information they're looking for.

Add collapsibles to the sidebar

With the Design decided on in #183 there's a sidebar being added that will allow a user to select an option. This option will then expand into several other options that a user can select.

This functionality needs adding. It's also important that when a user selects another item the previous selection is collapsed again.

Create an SPM guide for Getting Started

Documentation reference for Learn page.

Documentation Structure:

• Getting Started
  • Setting Up Prerequisites?
  • Configuration: A section on how to configure a Kitura project?
  • Kitura CLI (Split this up?)
  • macOS app
  • SPM
• Logging
• Routing
  • What is routing?
  • Raw Routing
  1. Terminology help (i.e. what is response? Request?)
  2. How to implement each route (GET, POST... etc etc)
  • Codable Routing
  1. Terminology help (i.e. What is Codable? Why use this routing?)
  2. How to implement each route (GET, POST... etc etc)
• Middlewares
  • What is a Middleware?
  • Raw middlewares
  • Type-safe middlewares
• Monitoring
• OpenAPI
• Databases
  • What are Databases? Uses?
  • Swift-Kuery
  • ORM
  • Plugins (MySQL, PostgreSQL, SQLite)
  • CouchDB/Cloudant?
  • Redis
• Sessions
  • What are sessions? Why would a user need them? Terminology help?
  • Raw Sessions
  • Type Safe sessions (codable)
• Authentication
  • What is Authentication? Why would a user need them? Terminology help?
  • Basic Auth
  • JWT Auth
  • Facebook, Google Token Auth
  • Facebook, Google, App ID: Similar? (Oauth2)
• Web Apps
  • What is Templating? Terminology help?
  • Stencil
  • Markdown
  • HTML Forms
• Deploying a project
  • Docker
  • Kubernetes
  • Cloud Foundry
• iOS Client
  • KituraKit Do we need this? Or should it be a part of the deployment section?

---

Currently the docs are a little scattered/unstructured, we should group together our documentation and fill in any doc gaps we have.

Above is a first draft of a potential documentation reference structure (i.e. The list that would appear down the side of a documentation page, and would allow a user to navigate via links).

The text in Bold with bullet points shows headings and sub headings. The numbered lists show the contents of an individual documentation page.

Ensure that the docs are opened inside the current page

When a user selects which guide they wish to view the guide should be opened within the current window, not in a new window/tab.

This is following the design set out in #183

Footer is off-center

Design a new layout for the documentation page

Currently the learn.html isn't very accommodating to an increasing number of documentation guides.

A new layout for the page is needed that will allow more guides to be easily added.

1. Remove the cards - It's unfeasible to categorise items into only 4 sections.
2. Group like content more efficiently.
3. Improve navigation around the docs.

Have API button link update based on what docs the user is currently viewing

The API docs for Kitura (and it's packages) are located in separate unlinked locations.

It'd be useful, in the long run, for a webpage to be added that'd link all the API docs to a single location.

For this issue however we should have the API Reference button update to link out to the guides that the user is currently viewing.

Create an OpenAPI guide for Routing

Create a Swift-Kuery guide for Databases

Create a Configuration guide for Getting Started

Create a Raw middlewares guide for Middlewares

Desktop menu disappears after sequence of actions

Steps to reproduce:

1. View the webpage in a mobile-size window (less than 899px wide)
2. Click to open the menu
3. Click to close the menu
4. Resize the window back to desktop size

Current workaround:
Refresh page.

Extra horizontal space in tutorials page on mobile screens

when we swipe left in tutorials page on mobile screen there is little blank space due to over size of todo-image.

Screenshot:

It should be look like this :

Create a Helium Logger guide for Logging

Parsing JSON Posts : about adding SwiftyJSON to Package.swift

Hi :)
I was trying to pasing requests tutorials from kitura.io

I don't understand why this expression should be in there
"Import SwiftyJSON by adding it to your Package.swift file".
that make me more confused

I thought 'I should add extra dependency?'. So I added dependency in Package.swift.
but it make build errors.

because SwiftyJSON already cloned by just adding 'Kitura.git'.

So "Import SwiftyJSON by adding it to your Package.swift file" should be in there?

Create a Raw Routing guide for Routing

Use page.lang variable to handle future translated content

Assuming we get community translations in the future, we need to use the /{{ page.lang }}/ variable in links so that when contributors copy the English files they don't have to manually update all the links.

Create a `What are Databases?` guide for Databases

Extra horizontal space in getting-started page on mobile screens

This is same issue as #70 on getting started page.

Screenshot 1:

Screenshot 2:

It should be look like this:

Remove `defer { next() }` from tutorials

Deferring next() causes the response to be sent before error handlers get called (if an error is thrown). I've asked about this on Slack several months ago and got confirmation that this is indeed an anti-pattern. I believe it was @shmuelk who confirmed this, but I am not sure.

Unfortunately, many developers new to Kitura still use it, most likely because it is still used on kitura.io, for example in: http://www.kitura.io/en/resources/tutorials/templating.html

Improve the design and layout of the documentation

This epic aims to improve the user experience around viewing and finding documentation.

Create a `What is a Middleware?` guide for Middlewares

Create a `What is Logging?` guide for Logging

Application Metrics for Swift Documentation Outdated

The documentation on the Learn - Application Metrics for Swift page is currently outdated. SwiftMetrics is now already included when using kitura init, and adding the code as instructed starts a second SwiftMetrics instance leading to the dashboard displaying multiple versions of each metric (e.g. memory, cpu, etc.):

Environment Details

macOS 10.13.5, Swift 4.2.1, Xcode 9.4.1

Steps to Reproduce

1. Run kitura init to create a new project
2. Follow the steps on the Learn - Application Metrics for Swift page to add SwiftMetrics to the project
3. Run the project and access the SwiftMetricsDash from localhost:[port_no]/swiftmetrics-dash
4. Each metrics graph is duplicated multiple times and are incorrectly displayed.

Missing steps in documentation for Swift Server Generator

Missing steps in documentation for Swift Server Generator

The getting started documentation is missing a few steps for the creation process.

The flow should be:

? What's the name of your application?
? Enter the name of the directory to contain the project:
? Select type of project:
? Select capabilities: (Press <space> to select, <a> to toggle all, <i> to inver
se selection)
? Select data store:

Slack / Github icon alignment on FHD screen (Android/Chrome)

On my Android mobile, the appearance of the new icons on Kitura.io is crowded toward the centre, as if there is too much fixed padding to their right:

This is viewing in Chrome on a full HD screen (1080 x 1920) in portrait.

Additionally, whilst the Slack icon is nice and clear, the Github and StackOverflow icons are fuzzy (low resolution) when zoomed beyond the default level.

Add a new webpage for API docs

Currently the API docs are located in several unlinked locations.

It'd be useful to add a new page that brings all these API docs together into one location to allow a user to easily navigate through the all API docs for each of our packages.

The structure of this new API Docs page could be similar to the design in #183.