openownership / data-standard-sphinx-theme Goto Github PK

That is: for text marked up like

statementGroups

... style it as Matt recommends.

As far as I can see requirements.txt is not used anywhere (the one from data-standard is used instead). Can we just remove it?

The same goes for requirements.in, but that list might eventually want to move to setup.py.

Found this animation/transition that would be sweet if we could implement for when the user is opening and closing the menu items in the sidebar. just going for the transition effects here rather than the visuals, something like this would be sweet. Ta

https://codepen.io/matthewhirsch/pen/rLOYGr

At present none of the assets for the data standard page are minified. Uglify has already been added as a dependency but is not used as part of the grunt pipeline. In the first instance this should be added as part of the existing pipeline.

Alternatively, more modern pipeline processes or bundlers could be considered (i.e. webpack etc).

Related: #57

At the moment on hovering over those menu items you get a black on dark turquoise. Try the yellow (#fdd106) instead.

There is a prominent link on the current theme to 'Edit on GitHub'

Whilst we will be inviting people to contribute to the documentation, we should downplay the idea of making direct documentation pull requests.

I would suggest for now we either:

(a) Remove the 'Edit on GitHub' link entirely;

(b) Move this to be a low-key link in the footer.

(Is this a theme issue at all? Maybe this is set in the docs markdown somewhere, but I couldn't find it.)

For the schema reference page, we need a bit more width.

Ideally changing, for this page only, from 42 to 62rem:

.oods-main {
    max-width: 62rem;
    margin: 0 auto;
}

Most people won't need to build the Bootstrap theme each time and this will be faster.

See http://standard.openownership.org/ru/0.2-dev-ru-translation/ where

"Beneficial Ownership Data Standard"

is not translated.

Checking in https://www.transifex.com/OpenDataServices/bods-theme/translate/#ru/sphinx-pot/163569068 shows that this did not get pushed up to Transifex.

I re-ran python setup.py extract_messages locally and pushed to Transifex (as per https://github.com/openownership/data-standard-sphinx-theme) and I don't see the string in either my local oods/locale/sphinx.pot file or in Transifex.

Note that we currently have an issue raised by our reviewer on how "Beneficial Ownership Data Standard" should be translated, depending on context. That shouldn't block us from investigating this issue.

Don't think this is actually used for anything.

Something like?

h2, .h2 {
font-size: 1.6rem;
margin: 2.5rem 0 1rem;
}

Suggestion:

.oods-main {
max-width: 38em;
}

If possible, add a section title/link to the sidebar menu (to aid with user orientation). E.g.

About

Credits
Governance

Needed for I18N

For example this page currently looks like this:

Even just having each list item styled as a big button would improve the look and feel. (TBH I don't think there's an existing style in Matt's work that can be applied here; the button styles aren't quite right.)

Maybe this is something we could ask Matt to look at when he works with us on 12th June?

We're making use of Transifex to translate the schema and docs. See the readme here

Users need to be able to:

• Checkout and build any release of the docs in any available language (meaning that both the theme and the docs would be built in the given language).
• Push changes to the English language version of the docs, for a given docs branch, to the related Transifex project for translation.

Changes may need to be made to the vagrant box to enable these tasks.

We're not currently using Google Analytics to track readership of the documentation (ReadTheDocs admin)

And currently there's no in-built RTD analytics

If there is no other mechnism, then we should get something in place.

I think we're going to hear from people that there isn't enought seperation and it's to hard to press the menu.

Links in the main content area don't stand out enough from the body text. A quick fix would be adding 'text-decoration: underline' to 'oods-main a'.

For a prettier fix, I can ask Matt to look at this on 12th June.

I've recently renamed all the released branches in the standard repo, so that we can take advantage of ReadTheDocs' ability to inject warning banners for viewers of older versions.

This works fine for 0.0.1->0.0.3 which use a standard theme, but doesn't work in 0.1.0 or 0.2.0 which use our custom theme. We need to figure out why (have we lost/overridden a bit of the default layout?). Once they appear, I think we'll also have to style them to fit into the theme better.

In addition, we should remove the warnings we manually added to the 0.0.x versions, as they're now duplicated.

The highlights directive is working, creating HTML like this:

<blockquote class="highlights">
<div><strong>Beneficial ownership</strong> is the right to some share of a legal entity’s income or assets (ownership) or the right to direct or influence the entity’s activities (control).
</div></blockquote>

A style something like this would be good:

blockquote.highlights {
margin: 2em 0 1em;
border: solid #fdd106;
border-width: 1px 1px 1px 10px;
border-radius: 4px;
padding: 25px 30px;
font-size: 120%;
}

Links are the primary green with the lighter green as for the underline. The underline is set as a border bottom rather than text decoration. This then also fills in on hover.

Here's a code pen
https://codepen.io/anon/pen/KemqBE

I think for the moment just centring images in the main column will work. (We don't need borders or anything.)

For example, when following a link to the entityStatement section of the schema reference:

/schema.html#entitystatement

... the 'EntityStatement' heading is hidden under the top menu.

$navbar-light-hover-color: #c4c4c4 !default;

Does the highlight text colour, but need to do the underscore and the unselected items.

From @M4TEU5's work on 12th June 2018.

We'd like to make the standard documentation feel more like an OpenOwnership product and less standalone. I believe the intention originally was to maintain and project its independence, but the current belief is that this is more detrimental to the use of the standard than a benefit.

Practically, this looks like:

• Using the standard fonts for headings (Publico Headline) and body text (Atlas Grotesk) and the same sizes (tba)
• Using the brand colour (#3d30d4) for links in body text, primary calls to action and highlights
• Using the OO favicon
• Adding some (presumably small) form of the OO logo to the header, and the main logo to the homepage (somewhere, tba)
• Styling the navigation to approximate the main navigation of openownership.org (black background, white links, brand colour underline on active pages
• Updating the body and copy to be the same 'black' on 'white' (or 'light grey') as openownership.org (exact colours from the styleguide, tba)

(I'm not sure if this best belongs as part of the theme, or as part of the docs repo: but putting here to avoid it getting lost amongst standard issues)

We use docson as a schema viewer.

At present this is a sub-module in the docs /_static/ folder.

The version we use does not have this fix in which we need: https://github.com/lbovet/docson/pull/41/files to handle json pointers in external files

There are three things we need to address:

• (1) Decide whether this should be part of the theme instead? (I'm agnostic)
• (2) Make sure our readme guidance and build processes properly initialise the submodule OR move to just using a static rather than sub-module copy
• (3) Make sure we can use a copy with https://github.com/lbovet/docson/pull/41/files fix applied

At the moment a page in the third tier like:

Data schema > Technical Requirements > Provenance info

... does not have a correctly structured breadcrumb and the page is not bolded etc in the side-panel navigation as you might expect. See the image below:

I think not - if you do so it will use the theme installed by pip and not the local theme in /vagrant

But that means this step is only needed by people who want to actively work on the theme - so we can improve the instructions!

Between

    'sphinxtheme/static/bootstrap-4.0.0/js/*.js'
    'sphinxtheme/static/bootstrap-4.0.0/js/*.js.map'

Can we please have the cards on the front page looking a bit more like this? i.e.:

• grey borders
• border-radius
• more margin around cards
• one-off style change for links: no underline

Menu items in the Nav Bar, Bread crumbs, and body should all be aligned and centered within the space from the side bar. Thanks!

Example: headings in whatisbo should not be in TOC

I'd like to be able to control the TOC appearing in the sidebar without the TOC appearing within a markup page.

Using the 'hidden' option for the TOC directive hides it within the main page as expected -

.. toctree::
:hidden:
:maxdepth: 1

credits.md
governance.md

But it also hides the TOC contents from the sidebar. According to this Sphinx issue there is a way of pulling in those hidden items to the sidebar. (Calling toctree() with includehidden=True.)

Build this About page to see what I mean.

Introduced more space around the search bar and squared owf it's edges.

Suggestion:

body {
font-size: 1.15rem;
line-height: 1.6;
}

Main content column to have a fixed max width. Centre on page.

Ideally top menu and side bar to be fixed and not scrollable.

I've removed the dark grey background colour introduced heaps more space ( as we don't seem to have that many items across the board (but nowt wrong with scrolling. There is a screenshot on the drive that contains different elements, current section. Hover, sub-section, current selection of a subsection ;)

With expand / collapse as in design mockups

@odscjames I think this highlight line needs to be wider: at least 4px (not 2px). And the padding under the nav elements (.py-4) reduced to maybe 1rem?

I have increased the line height of the type, added in more space before and after elements.

See console on http://standard.openownership.org/ru/0.2.0/

For some reason, other languages load these fonts from _static/fonts. The RU version loads them from there and tries to get them from the boostrap folder as well. I have no idea why at this stage, but it is replicable in the dev vagrant box:

• Check out master of this repo
• Checkout 0.2.0 of the standard within
• Build with BODSLANG=ru build-all

This isn't a major issue, as it doesn't seem to actually break any displayed fonts on the live docs, but it would be nice to clear up.

On this page, the tables are really not very user-friendly.

I'm not sure what our options are for re-formatting and styling these tables are. i.e. how difficult reformatting them as two columns would be eg

... versus the easy option of styling the tables differently.

We'd like to use Bootstrap 'cards' or similar for a front page like this:

https://drive.google.com/file/d/1ylaUl_DwkdS4C77KUfx9bvNWXnEMhelG/view

The old schema browser here allowed the user to click on an object and see its structure. (For example, in 'statementGroups array Statement group', the 'Statement group' is a clickable button.)

As the docs are now building, the same functionality is not present.

4. Copy the bits from add-to-conf.py into the real conf.py ( TODO we need to do better with this step! )

Should have a slight shadow on to help lift it from the main content.

maximum 1 argument(s) allowed, 3 supplied.

When it is working, all csv-table directives need to be changed to this.

Currently "Docs" is hardcoded in https://github.com/openownership/data-standard-sphinx-theme/blob/master/themes/oods/breadcrumbsedit.html#L4