Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ ablog==0.11.12
sphinx-reredirects==0.1.6
sphinx_design_elements==0.4.0
sphinx-tags
sphinx-multitoc-numbering
sphinxcontrib-mermaid
graphviz

Expand Down
72 changes: 33 additions & 39 deletions source/_ext/qms_header.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,46 +22,30 @@ def normalize_author_name(name: str) -> str:
return AUTHOR_NAME_MAP.get(name, name)


def create_header(document_reference, author_datetime, commit_datetime, git_sha, last_author):
"""Create the QMS header as a collapsible details element."""
# Create a collapsible details element with accessibility attributes
details_open = nodes.raw('', '<details class="qms-header" role="group" aria-label="Document information"><summary aria-expanded="false">Document Information</summary>', format='html')
details_close = nodes.raw('', '</details>', format='html')
def create_header(document_reference, author_datetime, commit_datetime, git_sha, last_author, include_hr=False):
"""Create the QMS header using sphinx-design dropdown HTML structure."""
# Use the exact same HTML structure as sphinx-design dropdown
# Match the Related Resources format exactly

# Add hr before the dropdown if the page doesn't have a Related Resources section
hr_html = '<hr class="qms-header-divider">' if include_hr else ''

dropdown_html = f'''{hr_html}<details class="sd-sphinx-override sd-dropdown sd-card sd-mb-3 qms-header">
<summary class="sd-summary-title sd-card-header">
<span class="sd-summary-text">Document Information</span><span class="sd-summary-state-marker sd-summary-chevron-right"><svg version="1.1" width="1.5em" height="1.5em" class="sd-octicon sd-octicon-chevron-right" viewBox="0 0 24 24" aria-hidden="true"><path d="M8.72 18.78a.75.75 0 0 1 0-1.06L14.44 12 8.72 6.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0Z"></path></svg></span></summary><div class="sd-summary-content sd-card-body docutils">
<ul class="simple">
<li><p class="sd-card-text"><strong>Reference:</strong> {document_reference}</p></li>
<li><p class="sd-card-text"><strong>Last Edited By:</strong> {last_author}</p></li>
<li><p class="sd-card-text"><strong>Last Edited:</strong> {author_datetime}</p></li>
<li><p class="sd-card-text"><strong>Effective from:</strong> {commit_datetime}</p></li>
<li><p class="sd-card-text"><strong>Git Commit:</strong> <a class="reference external" href="{gh_repo_url}/commit/{git_sha}">{git_sha}</a></p></li>
<li><p class="sd-card-text"><strong>Note:</strong> This is the current approved version. Printed or downloaded copies may be superseded; refer to <a class="reference external" href="{docs_site_url}">docs.bettercourses.org</a> for the authoritative version.</p></li>
</ul>
</div>
</details>'''

header_list = nodes.bullet_list()

# Document reference (file path)
header_list += create_item("Reference", document_reference)

# Last Edited By
header_list += create_item("Last Edited By", last_author)

# Last Edited (author date - when changes were made)
header_list += create_item("Last Edited", author_datetime)

# Effective from (commit date - when this version was approved/merged)
header_list += create_item("Effective from", commit_datetime)

# Git Commit with link to commit on GitHub
commit_link = nodes.reference(refuri=f"{gh_repo_url}/commit/{git_sha}")
commit_link += nodes.Text(git_sha)
header_list += create_item("Git Commit", commit_link)

# Document status note - deployed = approved
note_para = nodes.paragraph()
note_para += nodes.Text("This is the current approved version. Printed or downloaded copies may be superseded; refer to ")
docs_link = nodes.reference(refuri=docs_site_url)
docs_link += nodes.Text("docs.bettercourses.org")
note_para += docs_link
note_para += nodes.Text(" for the authoritative version.")
header_list += create_item("Note", note_para)

# Return wrapped in details element
container = nodes.container()
container += details_open
container += header_list
container += details_close

container += nodes.raw('', dropdown_html, format='html')
return container


Expand Down Expand Up @@ -181,12 +165,22 @@ def add_qms_header_to_doctree(app, doctree, docname):
else:
commit_datetime = "unknown"

# Check if the page has a Related Resources dropdown (preceded by hr)
# If not, we need to add an hr before Document Information
has_related_resources = False

# Check the full doctree text content for "Related Resources"
doctree_text = doctree.astext()
if 'Related Resources' in doctree_text:
has_related_resources = True

header = create_header(
document_reference,
author_datetime,
commit_datetime,
git_sha,
author_name
author_name,
include_hr=not has_related_resources
)

# Append the header to the end of the document
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
35 changes: 32 additions & 3 deletions source/_static/css/custom.css
Original file line number Diff line number Diff line change
Expand Up @@ -464,7 +464,6 @@ section#documentation-resources > h1 {
}

section#documentation-resources > p:first-of-type {
font-size: 0.95rem;
line-height: 1.6;
color: #4b5563;
margin-bottom: 0.5rem;
Expand All @@ -473,7 +472,6 @@ section#documentation-resources > p:first-of-type {
/* Link to main BCF site */
section#documentation-resources > p:nth-of-type(2) {
margin-bottom: 1rem;
font-size: 0.85rem;
}

/* Quick Links section heading */
Expand All @@ -482,7 +480,6 @@ section#quick-links {
}

section#quick-links > h2 {
font-size: 1.3rem;
margin-bottom: 1rem;
color: #374151;
}
Expand Down Expand Up @@ -528,12 +525,18 @@ section#documentation-resources {
/* Dropdown container */
details.sd-dropdown {
border: none !important;
border-left: none !important;
border-radius: 0.5rem !important;
margin-bottom: 0.5rem !important;
overflow: hidden;
box-shadow: none !important;
}

/* Remove left border from summary */
details.sd-dropdown > summary {
border-left: none !important;
}

/* Dropdown summary/header */
details.sd-dropdown > summary {
background-color: #f3f4f6 !important;
Expand Down Expand Up @@ -593,4 +596,30 @@ details.sd-dropdown > summary .sd-summary-icon {
details.sd-dropdown > summary:hover .sd-summary-icon,
details.sd-dropdown[open] > summary .sd-summary-icon {
color: white !important;
}

/* ============================================
Footer Section - Related Resources & Document Information
============================================ */

/* Horizontal rule before footer dropdowns - consistent spacing */
hr + details.sd-dropdown {
margin-top: 1.5rem !important;
}

/* The QMS header divider hr styling */
hr.qms-header-divider {
margin-top: 2rem !important;
margin-bottom: 0 !important;
}

/* When QMS header follows an hr directly (no Related Resources) */
hr.qms-header-divider + details.sd-dropdown.qms-header {
margin-top: 1.5rem !important;
}

/* Document Information dropdown - minimal gap after Related Resources */
details.sd-dropdown.qms-header {
margin-top: 0.5rem !important;
margin-bottom: 0 !important;
}
17 changes: 9 additions & 8 deletions source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,9 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'myst_parser',
'sphinx.ext.todo',
'sphinx_last_updated_by_git',
'myst_parser',
'sphinx.ext.todo',
'sphinx_last_updated_by_git',
'sphinx.ext.intersphinx',
# 'ablog', - note we conditionally add this in the following block
# 'sphinx_external_toc',
Expand All @@ -40,6 +40,7 @@
"sphinx_design",
"sphinx_design_elements",
"sphinx_tags",
"sphinx_multitoc_numbering",
"sphinxcontrib.mermaid",
"sphinx.ext.graphviz",
"qms_header",
Expand Down Expand Up @@ -71,7 +72,7 @@
# Ensure that PDFs are copied to the site by specifying the directories containing PDFs in the html_extra_path.
# This will copy the contents of the 'downloads' directory to the root of the build.

html_extra_path = ['robots.txt']
html_extra_path = ['robots.txt', 'downloads']


# Note everything in this folder will be copied to the root of the build
Expand Down Expand Up @@ -206,11 +207,11 @@

rst_prolog = """

.. _current-overview: /downloads/BC%20Course%20Overview.pdf
.. _current-overview: /BC%20Course%20Overview.pdf

.. _current-handbook: /downloads/BC%20Course%20Handbook.pdf
.. _current-handbook: /BC%20Course%20Handbook.pdf

.. _current-flipcharts: /downloads/BC%20Course%20Flipcharts.pdf
.. _current-flipcharts: /BC%20Course%20Flipcharts.pdf

.. raw:: html

Expand All @@ -235,7 +236,7 @@

redirects = {
# Old docs site paths → new locations
"documentation/200-the_course.index.html": "/course/index.html",
"documentation/200-the_course.index.html": "documentation/course/index.html",
"documentation/800-resources/email-templates.html": "/documentation/course-materials/email_templates.html",
# Old blog paths → BCF main site blog
"2023/05/02/modelling-sales.html": "https://betterconversations.foundation/blog/modelling-sales",
Expand Down
30 changes: 0 additions & 30 deletions source/course/60-Handbook-and-emails.rst

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,4 @@ Fancy a look behind the scenes? Here's how we work.

technical-stack
ai
stable-links
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ community. Following a `consultation with the community
<https://community.betterconversations.foundation/t/seeking-thoughts-on-a-code-of-conduct/557>`_,
the following Code of Conduct was adopted by the Board of Directors of the
Foundation at `their meeting of 27th February 2025
</work-with-us/governance/board/minutes-2025-02-27.html>`_.
/documentation/governance/board/minutes-2025-02-27.html>`_.


The Better Conversations team and community is made up of a mixture of
Expand All @@ -37,7 +37,7 @@ spaces may affect a person's ability to participate within them.
If you believe someone is violating the code of conduct, we ask that you
report it by emailing `contacting us here <https://betterconversations.foundation/about/contact>`_. For more
details please see our `Reporting Guidelines
</work-with-us/community/coc-reporting.html>`_.
/documentation/community/coc-reporting.html>`_.

* Be friendly and patient.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ The Better Conversations Community
==================================

You might think Better Conversations is a course, perhaps even a set of
flight plans. In fact, all of that comes from our community.
flight plans. In fact, all of that comes from our community.

The Foundation is a not-for-profit organisation that exists to support the
community.
Expand All @@ -16,10 +16,27 @@ subject to the Foundation's Employee Handbook and disciplinary process
which may be more stringent than the Code of Conduct, have different
processes, and have more severe penalties.

**What's available:**

- :doc:`coc` - our code of conduct
- :doc:`coc-reporting` - how to report issues
- :doc:`improvements-and-suggestions` - how to contribute improvements

----

.. dropdown:: Related Resources
:animate: fade-in

- **Partnership**: :doc:`/documentation/work-with-us/index` - working with the Foundation
- **Governance**: :doc:`/documentation/governance/index` - structure, policies, and board
- **Using the course**: :doc:`/documentation/using-the-course/index` - practical usage details

.. toctree::
:maxdepth: 2
:caption: Contents:
:caption: Contents
:hidden:

coc
coc
coc-reporting
improvements-and-suggestions

Loading
Loading