killbill / killbill-docs Goto Github PK

View Code? Open in Web Editor NEW

38.0 6.0 79.0 266.12 MB

Kill Bill documentation

Home Page: https://killbill.io

License: Apache License 2.0

Shell 4.03% Ruby 0.55% CSS 51.10% Slim 34.62% JavaScript 9.70%

killbill subscriptions billing payments

killbill-docs's Introduction

Docs

Kill Bill documentation (user guides and tutorials).

The site is built using Asciidoctor.

Edit and Syntax

The documentation is in the userguide directory.

AsciiDoc syntax: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/

Development

To generate the documentation locally:

make.sh

Generated html files are in the build directory.

To run the site locally:

ruby server.rb

Prerequisites:

Install Ruby (use RVM or RubyInstaller)
Run bundle install

Deployment

To deploy the docs:

make.sh
update_gh-pages.sh

Notes:

The generated static pages under build/selfcontained are pushed to the gh-pages branch (not served by GitHub pages)
The gh-pages branch is then deployed by Cloudflare (https://docs.killbill.io/)
Minification of assets is handled by Cloudflare (check-in the unminified version)

killbill-docs's People

Contributors

Stargazers

Watchers

Forkers

dlangille soitun cloudxtreme digideskio almalki andrenpaes kedarkdr hoandinhctk13 squaredave thamaraikrishnan matias-aguero-hs squaremike cognami danieljue vimvim mrluck8 anatoly-kudrevatykh-hs wwjfrodriguez sethdaugherty fieryorc javjimb wwjbatista liveqmock shericn mindia223 rmeuthen saad-2013 slomsubaie aavella77 ppohja paulkeogh stoica-florian huckleberryapps abishek2019 rupkumar6 nrtapia rowayda-khayri joeltaylor cgeduhn annabaker jdmooney poojanamdeo04 a-ostretsova mkhashoggi watthell234 sachgits bilal-arif-ivolve tasosce maryolinrestaino yashsrivastava16 rajnishkg saeed-farmanbar nekores-zz zero804 annabelschmitz12 chapins06 jidayangyang 0x0ece dev11levvel waelhamed karina0895 fbleite learnjavawithreshma richieroldan piyushkalasariya kbbitsp reshmabidikar slivas tryweirdier vnandwana the-code-robot forestvpn zenabhi xsalefter deekant getusha techechosystem rjrpaz bansal84k

killbill-docs's Issues

Remove and remove unneeded dependencies

We style load the following from document.html.slim:

https://stackpath.bootstrapcdn.com/bootstrap/4.1.1/css/bootstrap.min.css
https://cdn.staticaly.com/gh/afeld/bootstrap-toc/v1.0.0/dist/bootstrap-toc.min.css
https://stackpath.bootstrapcdn.com/bootstrap/4.1.1/js/bootstrap.min.js
https://cdn.staticaly.com/gh/afeld/bootstrap-toc/v1.0.0/dist/bootstrap-toc.min.js
https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap

Investigate if they are really still required, otherwise, get rid of them.

Address build warnings

asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/LoginScreen.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ChooseTenant.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/SignOut-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Homepage-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/killbill_logo_LARGER.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_PlusGreen.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_InvoiceGen.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_DownArrow.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_UpArrow.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_Tag.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_Plug.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_Addon.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_CreditCard.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_Gears.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_Refresh.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/GridSample.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/PaginationControls.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ShowSortArrowsOnColumn.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ShowSortByColumn.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ClickToViewDetail.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ShowTopSearch.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ShowSearchHomepage.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ShowAdvancedSearch.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AdvancedSearchPopup.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AdvSearch-ObjectTypeDropdown.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AdvancedSearchSyntax-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AccountPage_Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Account-Submenu.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/CreateNewAccount-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AddNewAccount.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Account_UpdateScreen.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_GrayDownArrow.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/PersonalInformation.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_PlusGreen.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AddNewEmail.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/NewContactEmail.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_GrayDownArrow.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_RedX.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/CloseAccountPopup.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AccountSubmenu-Closed.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AccountInfo-Section-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Account-TagDropdown.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_PlusGreen.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Account-ParentField-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/LinkToParentPopup.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Account-ParentID-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_GrayDownArrow.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/PaymentMethod-Expanded.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_StarClear.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/PaymentMethodStar-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_StarFilled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/PaymentMethods-PlusSign-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AddPaymentMethodScreen.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/PaymentMethodStar-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_GrayDownArrow.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Payment_Method-Transactions.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ProcessTransaction.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/TransactionKey-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_RedX.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoices.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice_Detail.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice_Detail.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice_MakePayment.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice_ProcessPayment.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice_Detail2.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_Tag.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice_WriteOffDropdown.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice_Detail3.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice_VoidDropdown.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/PayAllInvoices.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice-DryRunBox.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/Invoice-NextBillDate.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/i_InvoiceGen.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AddCredit-Labeled.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/AddNewChargePopup.png
asciidoctor: WARNING: plan_alignment.adoc: line 29: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: plan_alignment.adoc: line 39: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: plan_alignment.adoc: line 48: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: plan_alignment.adoc: line 57: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ecs-cluster.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ecs-cluster-fargate.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ecs-cluster-name.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ecs-cluster-success.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ecs-task-definition-fargate.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ecs-run-task-config.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/ecs-run-task-security-group.png
asciidoctor: WARNING: plugin_development.adoc: line 208: list item index: expected 1, got 3
asciidoctor: WARNING: plugin_development.adoc: line 214: list item index: expected 1, got 4
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/metrics-kb-admin.png
asciidoctor: WARNING: image to embed not found or not readable: /home/runner/work/killbill-docs/killbill-docs/userguide/assets/metrics-datadog-install.png
asciidoctor: WARNING: using-https.adoc: line 112: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: using-https.adoc: line 116: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: using-https.adoc: line 143: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: using-https.adoc: line 151: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: using-https.adoc: line 166: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: deploy_to_kubernetes.adoc: line 244: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: deploy_to_kubernetes.adoc: line 251: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: invoice_templates.adoc: line 140: list item index: expected a, got b
asciidoctor: WARNING: invoice_templates.adoc: line 156: list item index: expected a, got c
asciidoctor: WARNING: invoice_templates.adoc: line 161: list item index: expected 1, got 2
asciidoctor: WARNING: invoice_templates.adoc: line 194: list item index: expected a, got b
asciidoctor: WARNING: invoice_templates.adoc: line 210: list item index: expected a, got c
asciidoctor: WARNING: invoice_templates.adoc: line 218: list item index: expected 1, got 3
asciidoctor: WARNING: invoice_templates.adoc: line 229: list item index: expected a, got b
asciidoctor: WARNING: invoice_templates.adoc: line 245: list item index: expected a, got c
asciidoctor: WARNING: invoice_templates.adoc: line 250: list item index: expected 1, got 4
asciidoctor: WARNING: invoice_templates.adoc: line 267: list item index: expected a, got b
asciidoctor: WARNING: userguide_deployment.adoc: line 70: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: userguide_deployment.adoc: line 74: section title out of sequence: expected level 2, got level 3

e-commerce website integration guide

Subscription billing
- List available plans with prices (in Java and Ruby)
- Account and payment method creation APIs (in Java and Ruby)
- Combo subscription with add-ons API (in Java and Ruby)
- Display next invoice date and amount (in Java and Ruby)
- Subscription cancellation API (in Java and Ruby)
- Entitlement enforcement API (in Java and Ruby)
One-off items checkout
- Combo payment API (in Java and Ruby)

Title of the page should be present on the top right nav menu

From https://docs.killbill.io/latest/userguide_kaui.html;

broken links on userguide_payment.adoc

Showing
{sourcedir}/payment/includes/payment-api-overview.adoc
instead of an actual link to payment-api-overview.adoc

Database Migrations DDL link out of date

The database migrations guide (userguide/tutorials/database_migrations.adoc) has a link for the "latest" ddl file, along with a link to the http://killbill.io/downloads/ page. Both of these sources contain the DDL file for Kill Bill version 0.18, which is out of date. (the whole downloads page is for version 0.18, but that's a separate issue)

Might be best to just point to the github source (which is actually the first result if you google "kill bill ddl") to avoid needing to update it for each release.

remove bundlesPath and kpmPath

In setting up KPM in KAUI, we still have references to bundlesPath and kpmPath.

org.killbill.billing.plugin.kpm.bundlesPath=<kpm_bundles_path>
org.killbill.billing.plugin.kpm.kpmPath=<kpm_path>

Those are removed by this issue (its tasks and sub-sequence PRs): https://github.com/killbill/technical-support/issues/58. But we can't do it now (at the time of writing). Should wait at least after on going (at the time of writing) release.

After

The next page will give you several options for the launch method. Choose Launch through EC2.

, I think we need to make sure that user select/edit "Network Settings" in AWS Launch Form section and set "Auto-assign public IP" option.

Also, I think we can remove setup security rules section and merge with "Network Settings" above. See screenshot below.

Update: Also if possible, link in:

.... kaui schema: https://github.com/killbill/killbill-admin-ui/blob/master/db/ddl.sql

is not pointing to raw SQL file. I think it is better to poining directly to https://raw.githubusercontent.com/killbill/killbill-admin-ui/master/db/ddl.sql

Invoice and payment relationships guide

Go over:

Pure payment APIs use-cases
Pure invoice APIs use-cases (external charges, credits, ...)
Relationship between
- Invoices and Payment
- Subscription and Invoices

Developing a Payment Control Plugin guide

PaymentControlPluginApi overview
Overview of some of the use-cases:
- Payment routing
- Payments pre-processing
Invocation and pipelining using JAX-RS and the clients

Update AWS docs with plugin installation instructions

Update AWS docs with instructions on how to install a plugin.

More details here.

Wrong order for steps about how to create a multi-tier system

This is regarding: https://docs.killbill.io/latest/how-to-set-up-a-multi-tier-system

Steps to install a multi-tier seems to be fine according to the index. However the content does not follow the same order. As an example, Step 3 describes how to create two databases from an instance that is created in Step 5.

New docs site issue: Black area displayed when video is being played

When a video is being played on the docs site, UI displays a black area above and below the video:

Not sure if this has something to do with the browser/screen resolution.

Line numbering broken on some devices

Mac OS (broken):

Windows (working):

Left menu spacing issue

AWS documentation is out of date

(placeholder for potential PR)
https://github.com/killbill/killbill-docs/blob/v3/userguide/tutorials/aws.adoc

Shows out of date DDLs and Docker tags and blog links.

Investigate checked-in assets

In #499, the following files were checked-in. Do we still need them? Can they be upgraded?

Algolia pagination

We currently only return the first 5 results. We should instead allow the user to go through the pages of results.

Update to Asciidoctor 2.0.12

The update was done here: https://github.com/killbill/killbill-docs/tree/asciidoctor-update

We still need to verify the upgrade didn't break any page.

Generate left/right navigation

Goal: always keep the top navigation (from the index.html page) on the left, while displaying the in-page navigation on the right (similar to https://docs.asciidoctor.org/asciidoc/latest/).

A prototype has been done in the new-nav-prototype branch.

Notes:

The main navigation is now in html5/_main_toc.html.slim
In order to share the main navigation, the index.html has been converted to userguide/index/index.adoc, so that it is now generated like other files

This is what this currently looks like. Some obvious CSS work is still needed to prettify it:

Getting Started

Index.html

New website: Color of code snippet boxes in dark mode

Should we change the color of the code snippet boxes in Dark mode? It is a bit difficult to distinguish the code snippet box from the rest of the text:

Overdue tutorial updates for 0.16.x

How to test (making payments fail)

Re-generate diagram for 0.15.1

See killbill/killbill#347.

(cc/ @david-xie)

Migrate to DocSearch v3

See https://docsearch.algolia.com/docs/docsearch-v3/ (ping me for the new appId / apiKey)

Need to also setup GitHub Action: https://github.com/marketplace/actions/algolia-crawler-automatic-crawl

Self-host videos

This is to prevent ads: #505 (comment)

CSS iteration

Remove asciicast in userguide/index/index.adoc and embed https://www.youtube.com/watch?v=VEFqqHXOjlQ instead
Automatically expand one more level in the in-page table of content (on the right), so that the user can directly see all first-level headings and click on it directly (i.e. all top level nav-link behave like when active class is added)
Read more from the index as well as red in the navigation should match the official branded color we use everywhere (#167bb7 / #29a9c9/ #e44c3a)
Rework pygment CSS so that it matches the preview here: https://stylishthemes.github.io/Syntax-Themes/pygments/ (select the monokai highlighting theme)
Clicking on the top left logo (on any page) should redirect to https://docs.killbill.io/, not https://docs.killbill.io/0.22/
The tab for the documentation reads as "Untitled." It should read "Kill Bill Documentation"

Developing a Payment Plugin guide

PaymentPluginApi overview
PaymentPluginStatus states overview
ActiveMerchant plugin generation

While some of it is somewhat already covered in the main Payment guide, this guide should be tailored to plugin interactions with the gateways.

Review left menu CSS

Colors and wrapping make it hard to read

Add search

Integrate with https://docsearch.algolia.com/.

New docs site: White space displayed around text

White space is displayed on either side of the page content:

Is this intentional? It seems to make the page unnecessarily long and users require additional scrolling.

New docs site: Width of left nav bar adjustable

Wondering if we should make the width of the left navigation bar adjustable? Currently, it displays as follows for me:

I think it would be good to have the option to make the left navigation bar narrower so the main page content has a larger area for display.

Create Usage Plugin API doc

A usage plugin API doc needs to be created similar to the entitlement plugin doc. This should cover the use cases for usage plugin API.

```suggestion

    ```suggestion

Payment plugins integrate Kill Bill with a specific https://docs.killbill.io/latest/Kill-Bill-Glossary.html#payment_gateway[gateway] (i.e., payment processor), such as Stripe or Braintree. We already have many open-source payment plugins available on GitHub as listed in our https://docs.killbill.io/latest/plugin_introduction.html#payment_gateways[_Plugin Introduction_] guide.


_Originally posted by @FlowWriter in https://github.com/killbill/killbill-docs/pull/413#discussion_r981584697_

Unclear definitions for "entitlement" and "subscription"

There's no clear definition of these concepts in the doc, and they are non-trivial for a newbie.

in http://docs.kill-bill.org/userguide.html I find a definition for entitlement:
"An Entitlement encapsulates all the information that pertains to the entitlement question" which is recursive and not very clear; and "A Subscription is a meta abstraction that encapsulates the Entitlement and adds additonal billing information." which is not very clear either (I'm not sure what a "meta abstraction" is... also note the typo "additonal")

Here's some simplier definition that I would suggest:
"An entitlement determines whether a user is allowed to use a product a product at a given time. It refers a plan (i.e. product definition, billing period definition - monthly, yearly…) as well as possibly information about start/end date of access to the product. However, entitlements don't include billing information - they don't have anything about when and how much the user will be billed: they are only about usage of the product."

"A subscription defines how the entitlement given to the account will be billed: it includes entitlement information, and adds to it billing information such as billing start date, end date"

Probably having a clear glossary / concept definition section with these definition (as well as: Bundle; Plan; and probably a few others) would help a lot.

Thanks Kevin P. for help on this :)

Invoice templating and localization tutorial

Invoice template example with logo, company details and custom wiring instructions footnote
Invoice localization example where the previous invoice is sent to a French account:
- Invoice translated to French
- Line items in French (catalog translation)
- Numbers formatting ($1,499.95 becomes 1 499,95 €)

Developing an Invoice Plugin guide

InvoicePluginApi overview
Use-cases
- taxes
- pulling external charges from third-party billing systems

A hyperlink is pointing to 127.0.0.1

https://killbill.github.io/slate/#payment-transaction

In first sentence,
"Payment transactions belon to a Payment object."

Hyperlink associated with word "Payment" points to 127.0.0.1

Also you can fix the typo "belon" while you're at it.
Happy days! :D

NodesInfo APIs guide

NodesInfoResource overview:
- PluginInfo and NodeCommand descriptions
- use-cases
- multi- vs mono-node(s) commands
Snippets with cURL and Java/Ruby
Developing your own node command plugin

Libraries updates

Follow-ups on #173:

Acceptance criteria: for the task to be complete, all pages (e.g. https://docs.killbill.io/latest/getting_started.html) must have a similar CSS and existing functionality should not be broken (e.g. menus or code highlighting).

OSGI JDBC configuration property name seems wrong

Deploying my plugin, I've used the org.killbill.billing.osgi.jdbc.url system property name, but that seems to have changed somewhere in the code...

I noticed that by setting the org.killbill.billing.osgi.dao.url everything seems to work all-right!

missing information in add certificate in ACM

At the time of writing this issue, setup CNAME section in this docs need more explanation.

[1] .... The two strings labeled Name and Value should be copied to the two required entries for your CNAME. Copy these long strings carefully. Do not include any trailing periods. ....

Not all DNS manager in domain registrar should copy all those strings in ACM's CNAME name column. GoDaddy and Google Domains only need a prefix. See this so post.

[2] Your second CNAME is simpler. The Name entry will be kaui. The Value entry is the DNS name of your Load Balancer.

We need to add one or two paragraphs about the purpose of this. Maybe explain explicitly that we need 2 CNAME in our DNS Manager:

For ACM validation
For KAUI
For Kill Bill API it self, if needed (For discussion: I'm little bit confused as well about where we should put this information. Java Client for example, need extra work -- set certificate etc. if certificate is not valid or it is just self-signed certificate).

Potentially Lead To Misleading Info in Create Listener section

Currently, in Create Listener:

.... Next you will need to click on Add Listener to create a second Listener. This listener will use port 8443

I'm not sure the purpose of this. But, if this is supposed to handle an API request (Kill Bill backend) from internet, like various Kill Bill clients, etc. I think this is won't work.

Since Kill Bill and KAUI use the same Load Balancer (and thus sharing the same Load Balancer's DNS name, like kbhp-loadbalancer-XXX.us-east-1.elb.amazonaws.com), we can't register killbill backend to domain registrar CNAME because CNAME only support <host>. We can't set <host:port>.

Furthermore, If we remove port 8443 listener above, this section in Create Target Group should be updated as well:

Next, you need to perform the same steps for the second listener. This listener will handle messages directed to the Kill Bill server ....

Solution: If the purpose of creating listener in port 8443 is to make killbill API available to internet, I think the correct action would be Creating 2nd Load Balancer, just for Kill Bill API.

Overdue system docs problem.

the overdue docs indicates that plugin-installation API is :

curl -v \
-u admin:password \
-H "Content-Type: application/json" \
-H 'X-Killbill-CreatedBy: stephane' \
-X POST \
--data-binary '{"systemCommandType":"true","nodeCommandType":"INSTALL_PLUGIN","nodeCommandProperties":[{"key":"pluginKey", "value":"payment-test"},{"key":"pluginArtifactId", "value": "payment-test-plugin"},{"key":"pluginGroupId", "value": "org.kill-bill.billing.plugin.ruby"}, {"key": "pluginType", "value": "ruby"} ]}' \
"http://127.0.0.1:8080/1.0/kb/nodesInfo"

However, the correct field name is isSystemCommandType rather systemCommandType.

And thank you for opensource such an awesome project.

Update blocking states documentation

Review https://groups.google.com/g/killbilling-users/c/UW9Whktvwog and https://groups.google.com/g/killbilling-users/c/zDRfR4fYEQs and update blocking states documentation as required.

Invoice Subsystem and Parked States

Review and https://groups.google.com/g/killbilling-users/c/l69g92ItRqs and, if relevant update Invoice Subsystem document (Parked States section).

Also, the links do not display correction in the last paragraph of that section.

Tutorial: explain response objects and failures scenarii for payment (method) APIs

This was suggested by @galenp

Update "Deploying by Hand" Section in Plugin Installation

As discussed here, deploying by hand section need more clarity, especially about killbill-platform's bundles installation.

Update: Jan 24, 2023:

Also, please take a look this PR. Graphite, Influxdb and Prometheus README.md contains the same phrase, ".... If the property is not configured .... please check setting up KPM in Kaui". Once this updated, those README.md should refers to this up-to-date document, to avoid duplication.

KillBill Doc: payments.state_names can be improved

http://docs.killbill.io/0.14/userguide_payment.html#_payment_states_and_abstractions

Change FAILED,ERRORED (x2) to {AUTH,CAPTURE,..}_FAILED, {AUTH,CAPTURE,..}_ERRORED

Change {AUTH,CAPTURE,..}_PENDING -->{AUTH,PURCHASE}_PENDING