Skip to content

fix+enh(sphinx): Remove dup versions in title + weird title combination + don't use latest on older docs + add real version #11628

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

fix+enh(sphinx): Remove dup versions in title + weird title combination + don't use latest on older docs + add real version #11628

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
40d24ae
fix(admin): Eliminate duplicate version string from HTML title
joshtrichards Mar 8, 2024
1f64658
enh(sphinx): Add global project title
joshtrichards Mar 8, 2024
1bf42ae
enh(sphinx): Automatically determine version string
joshtrichards Mar 8, 2024
8d7822a
fix(dev): Eliminate duplicate version string from HTML title
joshtrichards Mar 8, 2024
0b77029
fix(user): Eliminate duplicate version string from HTML title
joshtrichards Mar 8, 2024
f76bae9
Tweak get_version
joshtrichards Mar 8, 2024
ff1c01e
Adjust titles
joshtrichards Mar 8, 2024
f8ee026
Adjust logic for clarity
joshtrichards Mar 8, 2024
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
7 changes: 4 additions & 3 deletions admin_manual/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@
#release = '12'

# General information about the project.
project = u'Nextcloud %s Administration Manual' % (version)
#project = u'Nextcloud %s Administration Manual' % (version)

#copyright = u'2012-2017, The Nextcloud developers'


Expand Down Expand Up @@ -109,10 +110,10 @@
# }
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
html_title = "%s Administration Manual" % (project)

# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = "Server Admin Manual"
#html_short_title = "Server Admin Manual"

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
Expand Down
23 changes: 21 additions & 2 deletions conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,29 @@
# global configuration for every documentation added at the end

import os, sys, datetime
from subprocess import Popen, PIPE

import sphinx_rtd_theme

dir_path = os.path.dirname(os.path.realpath(__file__))
sys.path.insert(0, os.path.abspath(dir_path + '/_ext'))
now = datetime.datetime.now()

def get_version():

pipe = Popen('git branch | grep \*', stdout=PIPE, shell=True, universal_newlines=True)
version = pipe.stdout.read()

null, version = version.split("*",1)
version = version.strip()

if version == "master":
return "upcoming"
elif version[:6] == "stable":
return version[-2:]
else:
return "%s" % (version)

extensions = ['sphinx_rtd_theme', 'sphinx_rtd_dark_mode']

# General information about the project.
Expand All @@ -18,10 +34,13 @@
# built documents.
#
# The short X.Y version.
version = 'latest'
version = get_version()
# The full version, including alpha/beta/rc tags.
release = version

# General information about the project.
project = u'Nextcloud Server (%s)' % (version)

# RTD theme options
html_theme_options = {
'logo_only': True,
Expand All @@ -33,7 +52,7 @@
html_logo = "../_shared_assets/static/logo-white.png"

# substitutions go here
rst_epilog = '.. |version| replace:: %s' % version
#rst_epilog = '.. |version| replace:: %s' % version

# building the versions list
version_start = 26 # THIS IS THE SUPPORTED VERSION NUMBER
Expand Down
4 changes: 2 additions & 2 deletions developer_manual/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
master_doc = 'index'

# General information about the project.
project = u'Nextcloud %s Developer Manual' % (version)
#project = u'Nextcloud %s Developer Manual' % (version)
#copyright = u'2012-2017, The Nextcloud developers'

# The version info for the project you're documenting, acts as replacement for
Expand Down Expand Up @@ -109,7 +109,7 @@
# }
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
html_title = "%s Developer Manual" % (project)

# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = "Developer Manual"
Expand Down
4 changes: 2 additions & 2 deletions user_manual/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@
#release = '12'

# General information about the project.
project = u'Nextcloud %s User Manual' % (version)
#project = u'Nextcloud %s User Manual' % (version)
#copyright = u'2012-2017, The Nextcloud developers'

# The language for content autogenerated by Sphinx. Refer to documentation
Expand Down Expand Up @@ -109,7 +109,7 @@
# }
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
html_title = "%s User Manual" % (project)

# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = "User Manual"
Expand Down
6 changes: 3 additions & 3 deletions user_manual/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
.. _index:

============================================
Nextcloud |version| user manual introduction
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is shipped as PDF file with the release, that's why we want to have the version number in there, iirc

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see the PDF (at least in v27 and v28). The help page loads the HTML doc.

The version is still in the PDF - on the title page for example. It's just that now instead of always saying latest (including above) no matter what version of the doc someone is looking at - it'll say the actual version.

I can see putting it back on that particular page maybe in the first paragraph or something. But it's weird IMO to have it embedded in the ToC entry for the Introduction Chapter (even if we do make it the correct version). I can see having it in place for the "What's new" chapter maybe.

I'll re-look a bit more at it maybe tomorrow. Already took longer than planned since I hadn't messed with the PDF builds before. They're... a little weird. :)

============================================
============
Introduction
============

**Welcome to Nextcloud: A safe home for all your data.**

Expand Down
6 changes: 3 additions & 3 deletions user_manual/whats_new.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
===========================================
What's new for users in Nextcloud |version|
===========================================
==========
What's new
==========

1. Easier way to select a new app:

Expand Down