Skip to content

Commit 5d640bf

Browse files
sethrjsethrj
committed
Update documentation
1 parent 40a443c commit 5d640bf

File tree

5 files changed

+65
-202
lines changed

5 files changed

+65
-202
lines changed

‎doc/CMakeLists.txt

+29-2
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,44 @@
44
## License-Filename: LICENSE
55
find_package(Sphinx REQUIRED)
66

7+
#-----------------------------------------------------------------------------#
8+
9+
# Define a configure file with version and configuration info
10+
if(ForTrilinos_VERSION STREQUAL ForTrilinos_VERSION_STRING)
11+
set(ForTrilinos_SHORT_VERSION "${ForTrilinos_VERSION}")
12+
elseif("${ForTrilinos_VERSION_STRING}" MATCHES
13+
"^(.*-rc[.-][0-9]+)(\\.[0-9]+\\+[0-9a-f]+)$")
14+
# Use release candidate, stripping off stuff since the tag
15+
set(ForTrilinos_SHORT_VERSION "${CMAKE_MATCH_1}")
16+
else()
17+
# Development version
18+
set(_patch "${PROJECT_VERSION_PATCH}")
19+
if(NOT ForTrilinos_VERSION_STRING MATCHES "-dev")
20+
# Before the next release
21+
math(EXPR _patch "${PROJECT_VERSION_PATCH} + 1")
22+
endif()
23+
set(ForTrilinos_SHORT_VERSION
24+
"${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${_patch}-dev"
25+
)
26+
endif()
27+
configure_file("config.json.in" "config.json" @ONLY)
28+
29+
#-----------------------------------------------------------------------------#
730
add_custom_target(doc)
831
add_custom_command(TARGET doc
9-
COMMAND "${SPHINX_EXECUTABLE}" -q
32+
VERBATIM COMMAND
33+
"${CMAKE_COMMAND}" -E env
34+
"CMAKE_CURRENT_BINARY_DIR=${CMAKE_CURRENT_BINARY_DIR}"
35+
"${SPHINX_EXECUTABLE}" -q
1036
-d "${CMAKE_CURRENT_BINARY_DIR}/doctrees"
1137
-b html
1238
"${CMAKE_CURRENT_SOURCE_DIR}"
1339
"${CMAKE_CURRENT_BINARY_DIR}/html"
1440
WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
1541
COMMENT "Building HTML documentation with Sphinx"
42+
DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
1643
BYPRODUCTS "${CMAKE_CURRENT_BINARY_DIR}/html/index.html"
17-
)
44+
)
1845

1946

2047
install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/"

‎doc/conf.py

+23-198
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,10 @@
11
#!/usr/bin/env python3
22
# -*- coding: utf-8 -*-
3-
#
4-
# ForTrilinos documentation build configuration file, created by
5-
# sphinx-quickstart on Thu Feb 23 20:41:01 2017.
6-
#
7-
# This file is execfile()d with the current directory set to its
8-
# containing dir.
9-
#
10-
# Note that not all possible configuration values are present in this
11-
# autogenerated file.
12-
#
13-
# All configuration values have a default; values that are commented out
14-
# serve to show the default.
153

16-
# If extensions (or modules to document with autodoc) are in another directory,
17-
# add these directories to sys.path here. If the directory is relative to the
18-
# documentation root, use os.path.abspath to make it absolute, like shown here.
19-
#
20-
# import os
21-
# import sys
22-
# sys.path.insert(0, os.path.abspath('.'))
4+
import os
5+
import json
6+
import sys
7+
from pathlib import Path
238

249
# -- General configuration ------------------------------------------------
2510

@@ -49,38 +34,31 @@
4934

5035
# General information about the project.
5136
project = 'ForTrilinos'
52-
copyright = '2017–2020, Oak Ridge National Laboratory, UT-Battelle, LLC'
37+
copyright = '2017–2023, Oak Ridge National Laboratory, UT-Battelle, LLC'
5338
all_authors = [
5439
"Seth R. Johnson",
5540
"Andrey Prokopenko"
5641
]
5742
author = " and ".join(all_authors)
5843

59-
# The version info for the project you're documenting, acts as replacement for
60-
# |version| and |release|, also used in various other places throughout the
61-
# built documents.
62-
#
63-
# The short X.Y version.
64-
# TODO: import from git/cmake-generated version
65-
version = ''
66-
# The full version, including alpha/beta/rc tags.
67-
release = ''
68-
69-
# The language for content autogenerated by Sphinx. Refer to documentation
70-
# for a list of supported languages.
71-
#
72-
# This is also used if you do content translation via gettext catalogs.
73-
# Usually you set "language" from the command line for these cases.
74-
language = None
75-
76-
# There are two options for replacing |today|: either, you set today to some
77-
# non-false value, then it is used:
78-
#
79-
# today = ''
80-
#
81-
# Else, today_fmt is used as the format for a strftime call.
82-
#
83-
# today_fmt = '%B %d, %Y'
44+
try:
45+
build_dir = Path(os.environ['CMAKE_CURRENT_BINARY_DIR'])
46+
with open(build_dir / 'config.json', 'r') as f:
47+
cmake_config = json.load(f)
48+
except (KeyError, IOError) as e:
49+
print("Failed to load cmake config data:", e)
50+
build_dir = '.'
51+
52+
cmake_config = {
53+
"version": "*unknown version*",
54+
"release": "*unknown release*",
55+
"options": {}
56+
}
57+
tags.add('noconfig')
58+
59+
version = cmake_config['version']
60+
release = cmake_config['release']
61+
html_title = f"{project} {version} documentation"
8462

8563
# List of patterns, relative to source directory, that match files and
8664
# directories to ignore when looking for source files.
@@ -235,21 +213,6 @@
235213
# -- Options for LaTeX output ---------------------------------------------
236214

237215
latex_elements = {
238-
# The paper size ('letterpaper' or 'a4paper').
239-
#
240-
# 'papersize': 'letterpaper',
241-
242-
# The font size ('10pt', '11pt' or '12pt').
243-
#
244-
# 'pointsize': '10pt',
245-
246-
# Additional stuff for the LaTeX preamble.
247-
#
248-
# 'preamble': '',
249-
250-
# Latex figure (float) alignment
251-
#
252-
# 'figure_align': 'htbp',
253216
}
254217

255218
# Grouping the document tree into LaTeX files. List of tuples
@@ -260,39 +223,6 @@
260223
r' \and '.join(all_authors), 'manual'),
261224
]
262225

263-
# The name of an image file (relative to this directory) to place at the top of
264-
# the title page.
265-
#
266-
# latex_logo = None
267-
268-
# For "manual" documents, if this is true, then toplevel headings are parts,
269-
# not chapters.
270-
#
271-
# latex_use_parts = False
272-
273-
# If true, show page references after internal links.
274-
#
275-
# latex_show_pagerefs = False
276-
277-
# If true, show URL addresses after external links.
278-
#
279-
# latex_show_urls = False
280-
281-
# Documents to append as an appendix to all manuals.
282-
#
283-
# latex_appendices = []
284-
285-
# It false, will not define \strong, \code, itleref, \crossref ... but only
286-
# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
287-
# packages.
288-
#
289-
# latex_keep_old_macro_names = True
290-
291-
# If false, no module index is generated.
292-
#
293-
# latex_domain_indices = True
294-
295-
296226
# -- Options for manual page output ---------------------------------------
297227

298228
# One entry per manual page. List of tuples
@@ -302,11 +232,6 @@
302232
[author], 1)
303233
]
304234

305-
# If true, show URL addresses after external links.
306-
#
307-
# man_show_urls = False
308-
309-
310235
# -- Options for Texinfo output -------------------------------------------
311236

312237
# Grouping the document tree into Texinfo files. List of tuples
@@ -317,104 +242,4 @@
317242
author, 'ForTrilinos', 'One line description of project.',
318243
'Miscellaneous'),
319244
]
320-
321-
# Documents to append as an appendix to all manuals.
322-
#
323-
# texinfo_appendices = []
324-
325-
# If false, no module index is generated.
326-
#
327-
# texinfo_domain_indices = True
328-
329-
# How to display URL addresses: 'footnote', 'no', or 'inline'.
330-
#
331-
# texinfo_show_urls = 'footnote'
332-
333-
# If true, do not generate a @detailmenu in the "Top" node's menu.
334-
#
335-
# texinfo_no_detailmenu = False
336-
337-
338-
# -- Options for Epub output ----------------------------------------------
339-
340-
# Bibliographic Dublin Core info.
341-
epub_title = project
342-
epub_author = author
343-
epub_publisher = author
344-
epub_copyright = copyright
345-
346-
# The basename for the epub file. It defaults to the project name.
347-
# epub_basename = project
348-
349-
# The HTML theme for the epub output. Since the default themes are not
350-
# optimized for small screen space, using the same theme for HTML and epub
351-
# output is usually not wise. This defaults to 'epub', a theme designed to save
352-
# visual space.
353-
#
354-
# epub_theme = 'epub'
355-
356-
# The language of the text. It defaults to the language option
357-
# or 'en' if the language is not set.
358-
#
359-
# epub_language = ''
360-
361-
# The scheme of the identifier. Typical schemes are ISBN or URL.
362-
# epub_scheme = ''
363-
364-
# The unique identifier of the text. This can be a ISBN number
365-
# or the project homepage.
366-
#
367-
# epub_identifier = ''
368-
369-
# A unique identification for the text.
370-
#
371-
# epub_uid = ''
372-
373-
# A tuple containing the cover image and cover page html template filenames.
374-
#
375-
# epub_cover = ()
376-
377-
# A sequence of (type, uri, title) tuples for the guide element of content.opf.
378-
#
379-
# epub_guide = ()
380-
381-
# HTML files that should be inserted before the pages created by sphinx.
382-
# The format is a list of tuples containing the path and title.
383-
#
384-
# epub_pre_files = []
385-
386-
# HTML files that should be inserted after the pages created by sphinx.
387-
# The format is a list of tuples containing the path and title.
388-
#
389-
# epub_post_files = []
390-
391-
# A list of files that should not be packed into the epub file.
392245
epub_exclude_files = ['search.html']
393-
394-
# The depth of the table of contents in toc.ncx.
395-
#
396-
# epub_tocdepth = 3
397-
398-
# Allow duplicate toc entries.
399-
#
400-
# epub_tocdup = True
401-
402-
# Choose between 'default' and 'includehidden'.
403-
#
404-
# epub_tocscope = 'default'
405-
406-
# Fix unsupported image types using the Pillow.
407-
#
408-
# epub_fix_images = False
409-
410-
# Scale large images.
411-
#
412-
# epub_max_image_width = 0
413-
414-
# How to display URL addresses: 'footnote', 'no', or 'inline'.
415-
#
416-
# epub_show_urls = 'inline'
417-
418-
# If false, no index is generated.
419-
#
420-
# epub_use_index = True

‎doc/config.json.in

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"version": "@ForTrilinos_SHORT_VERSION@",
3+
"release": "@ForTrilinos_VERSION_STRING@",
4+
"options": {}
5+
}

‎doc/index.rst

+5
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22
ForTrilinos
33
===========
44

5+
.. only:: html
6+
7+
:Release: |release|
8+
:Date: |today|
9+
510
.. toctree::
611
:maxdepth: 2
712
:caption: Contents

‎doc/install.rst

+3-2
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ the version here simply denotes the version used to generate the included
2222
wrappers.)
2323

2424
The version scheme is based on semantic versioning:
25+
2526
- Major version numbers with Trilinos and minor versions of SWIG-Fortran (since
2627
it's still not officially upstreamed) can result in major version number
2728
changes for ForTrilinos.
@@ -55,7 +56,7 @@ in the committed version of the generated wrappers.
5556
=========== ============== ======================
5657

5758
In :ref:`the version table above <version_table>`, the ``+fortran`` suffix for
58-
SWIG indicates `the SWIG-Fortran fork <https://github.com/swig-fortran/swig>`.
59+
SWIG indicates the `SWIG-Fortran fork <https://github.com/swig-fortran/swig>`_.
5960
``+sha`` refers to a specific Git commit that comes after the given version.
6061

6162
Basically, the versioning will be driven by what the Fortran-only users see in the committed version of the generated wrappers.
@@ -69,7 +70,7 @@ E4S
6970
---
7071

7172
As of this writing, ForTrilinos is distributed as part of the `E4S Project
72-
<https://e4s-project.github.io/index.html>` and should be available as a
73+
<https://e4s-project.github.io/index.html>`_ and should be available as a
7374
pre-built binary on a variety of user and HPC systems.
7475

7576
Spack

0 commit comments

Comments
 (0)