Skip to content

Commit

Permalink
docs: basic API reference docs (#128)
Browse files Browse the repository at this point in the history 
* Bump required ops version to 2.12 to get CloudSpec/CloudCredential.

* Bump version.

* Add generation of API reference documentation.

* Remove the jujulogline doc, which doesn't work correctly, and confuses the linter, which thinks it's the module docstring.

* Handle ops caching the content.
  • Loading branch information
@tonyandrewmeyer
tonyandrewmeyer authored Jul 9, 2024
1 parent 77ce447 commit c2253b7
Show file tree
Hide file tree
Showing 35 changed files with 2,385 additions and 49 deletions.
3 changes: 2 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
venv/
build/
docs/build/
*.charm
.tox/
.coverage
Expand All @@ -9,4 +10,4 @@ __pycache__/
*.egg-info
dist/
*.pytest_cache
htmlcov/
htmlcov/
13 changes: 13 additions & 0 deletions docs/.sphinx/_static/404.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
361 changes: 361 additions & 0 deletions docs/.sphinx/_static/custom.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,361 @@
/**
Ubuntu variable font definitions.
Based on https://github.com/canonical/vanilla-framework/blob/main/scss/_base_fontfaces.scss
When font files are updated in Vanilla, the links to font files will need to be updated here as well.
*/

/* default font set */
@font-face {
font-family: 'Ubuntu variable';
font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
font-style: normal;
font-weight: 100 800; /* min and max value for the weight axis */
src: url('https://assets.ubuntu.com/v1/f1ea362b-Ubuntu%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations');
}

@font-face {
font-family: 'Ubuntu variable';
font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
font-style: italic;
font-weight: 100 800; /* min and max value for the weight axis */
src: url('https://assets.ubuntu.com/v1/90b59210-Ubuntu-Italic%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations');
}

@font-face {
font-family: 'Ubuntu Mono variable';
font-style: normal;
font-weight: 100 800; /* min and max value for the weight axis */
src: url('https://assets.ubuntu.com/v1/d5fc1819-UbuntuMono%5Bwght%5D-latin-v0.869.woff2') format('woff2-variations');
}

/* cyrillic-ext */
@font-face {
font-family: 'Ubuntu variable';
font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
font-style: normal;
font-weight: 100 800; /* min and max value for the weight axis */
src: url('https://assets.ubuntu.com/v1/77cd6650-Ubuntu%5Bwdth,wght%5D-cyrillic-extended-v0.896a.woff2') format('woff2-variations');
unicode-range: U+0460-052F, U+20B4, U+2DE0-2DFF, U+A640-A69F;
}

/* cyrillic */
@font-face {
font-family: 'Ubuntu variable';
font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
font-style: normal;
font-weight: 100 800; /* min and max value for the weight axis */
src: url('https://assets.ubuntu.com/v1/2702fce5-Ubuntu%5Bwdth,wght%5D-cyrillic-v0.896a.woff2') format('woff2-variations');
unicode-range: U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
}

/* greek-ext */
@font-face {
font-family: 'Ubuntu variable';
font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
font-style: normal;
font-weight: 100 800; /* min and max value for the weight axis */
src: url('https://assets.ubuntu.com/v1/5c108b7d-Ubuntu%5Bwdth,wght%5D-greek-extended-v0.896a.woff2') format('woff2-variations');
unicode-range: U+1F00-1FFF;
}

/* greek */
@font-face {
font-family: 'Ubuntu variable';
font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
font-style: normal;
font-weight: 100 800; /* min and max value for the weight axis */
src: url('https://assets.ubuntu.com/v1/0a14c405-Ubuntu%5Bwdth,wght%5D-greek-v0.896a.woff2') format('woff2-variations');
unicode-range: U+0370-03FF;
}

/* latin-ext */
@font-face {
font-family: 'Ubuntu variable';
font-stretch: 100%; /* min and max value for the width axis, expressed as percentage */
font-style: normal;
font-weight: 100 800; /* min and max value for the weight axis */
src: url('https://assets.ubuntu.com/v1/19f68eeb-Ubuntu%5Bwdth,wght%5D-latin-extended-v0.896a.woff2') format('woff2-variations');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}


/** Define font-weights as per Vanilla
Based on: https://github.com/canonical/vanilla-framework/blob/main/scss/_base_typography-definitions.scss
regular text: 400,
bold: 550,
thin: 300,
h1: bold,
h2: 180;
h3: bold,
h4: 275,
h5: bold,
h6: regular
*/

/* default regular text */
html {
font-weight: 400;
}

/* heading specific definitions */
h1, h3, h5 { font-weight: 550; }
h2 { font-weight: 180; }
h4 { font-weight: 275; }

/* bold */
.toc-tree li.scroll-current>.reference,
dl.glossary dt,
dl.simple dt,
dl:not([class]) dt {
font-weight: 550;
}


/** Table styling **/

th.head {
text-transform: uppercase;
font-size: var(--font-size--small);
text-align: initial;
}

table.align-center th.head {
text-align: center
}

table.docutils {
border: 0;
box-shadow: none;
width:100%;
}

table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child {
border-right: none;
border-left: none;
}

/* Allow to centre text horizontally in table data cells */
table.align-center {
text-align: center !important;
}

/** No rounded corners **/

.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight {
border-radius: 0;
}

/** Admonition styling **/

.admonition {
border-top: 1px solid #d9d9d9;
border-right: 1px solid #d9d9d9;
border-bottom: 1px solid #d9d9d9;
}

/** Color for the "copy link" symbol next to headings **/

a.headerlink {
color: var(--color-brand-primary);
}

/** Line to the left of the current navigation entry **/

.sidebar-tree li.current-page {
border-left: 2px solid var(--color-brand-primary);
}

/** Some tweaks for Sphinx tabs **/

[role="tablist"] {
border-bottom: 1px solid var(--color-sidebar-item-background--hover);
}

.sphinx-tabs-tab[aria-selected="true"], .sd-tab-set>input:checked+label{
border: 0;
border-bottom: 2px solid var(--color-brand-primary);
font-weight: 400;
font-size: 1rem;
color: var(--color-brand-primary);
}

body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] {
background: var(--color-background-primary);
border-bottom: 2px solid var(--color-brand-primary);
}

button.sphinx-tabs-tab[aria-selected="false"]:hover, .sd-tab-set>input:not(:checked)+label:hover {
border-bottom: 2px solid var(--color-foreground-border);
}

button.sphinx-tabs-tab[aria-selected="false"]{
border-bottom: 2px solid var(--color-background-primary);
}

body[data-theme="dark"] .sphinx-tabs-tab {
background: var(--color-background-primary);
}

.sphinx-tabs-tab, .sd-tab-set>label{
color: var(--color-brand-primary);
font-family: var(--font-stack);
font-weight: 400;
font-size: 1rem;
padding: 1em 1.25em .5em
}

.sphinx-tabs-panel {
border: 0;
border-bottom: 1px solid var(--color-sidebar-item-background--hover);
background: var(--color-background-primary);
padding: 0.75rem 0 0.75rem 0;
}

body[data-theme="dark"] .sphinx-tabs-panel {
background: var(--color-background-primary);
}

/** A tweak for issue #190 **/

.highlight .hll {
background-color: var(--color-highlighted-background);
}


/** Custom classes to fix scrolling in tables by decreasing the
font size or breaking certain columns.
Specify the classes in the Markdown file with, for example:
```{rst-class} break-col-4 min-width-4-8
```
**/

table.dec-font-size {
font-size: smaller;
}
table.break-col-1 td.text-left:first-child {
word-break: break-word;
}
table.break-col-4 td.text-left:nth-child(4) {
word-break: break-word;
}
table.min-width-1-15 td.text-left:first-child {
min-width: 15em;
}
table.min-width-4-8 td.text-left:nth-child(4) {
min-width: 8em;
}

/** Underline for abbreviations **/

abbr[title] {
text-decoration: underline solid #cdcdcd;
}

/** Use the same style for right-details as for left-details **/
.bottom-of-page .right-details {
font-size: var(--font-size--small);
display: block;
}

/** Version switcher */
button.version_select {
color: var(--color-foreground-primary);
background-color: var(--color-toc-background);
padding: 5px 10px;
border: none;
}

.version_select:hover, .version_select:focus {
background-color: var(--color-sidebar-item-background--hover);
}

.version_dropdown {
position: relative;
display: inline-block;
text-align: right;
font-size: var(--sidebar-item-font-size);
}

.available_versions {
display: none;
position: absolute;
right: 0px;
background-color: var(--color-toc-background);
box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
z-index: 11;
}

.available_versions a {
color: var(--color-foreground-primary);
padding: 12px 16px;
text-decoration: none;
display: block;
}

.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}

.show {display:block;}

/** Fix for nested numbered list - the nested list is lettered **/
ol.arabic ol.arabic {
list-style: lower-alpha;
}

/** Make expandable sections look like links **/
details summary {
color: var(--color-link);
}

/** Fix the styling of the version box for readthedocs **/

#furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version {
background: var(--color-sidebar-item-background--hover);
}

.rst-versions .rst-other-versions dd a {
color: var(--color-link);
}

#furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions {
color: var(--color-sidebar-link-text);
}

.rst-versions .rst-current-version {
color: var(--color-version-popup);
font-weight: bolder;
}

/* Code-block copybutton invisible by default
(overriding Furo config to achieve default copybutton setting). */
.highlight button.copybtn {
opacity: 0;
}

/* Mimicking the 'Give feedback' button for UX consistency */
.sidebar-search-container input[type=submit] {
color: #FFFFFF;
border: 2px solid #D6410D;
padding: var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal);
background: #D6410D;
font-weight: bold;
font-size: var(--font-size--small);
cursor: pointer;
}

.sidebar-search-container input[type=submit]:hover {
text-decoration: underline;
}

/* Make inline code the same size as code blocks */
p code.literal {
border: 0;
font-size: var(--code-font-size);
}

/* Use the general admonition font size for inline code */
.admonition p code.literal {
font-size: var(--admonition-font-size);
}
Binary file added docs/.sphinx/_static/favicon.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit c2253b7

Please sign in to comment.