Ticket #9521 (closed: fixed)

Opened 6 years ago

Last modified 5 years ago

Create Python Sphinx directives to support new documentation style

Reported by: Martyn Gigg Owned by: Martyn Gigg
Priority: critical Milestone: Release 3.2
Component: Documentation Keywords:
Cc: Blocked By:
Blocking: Tester: Nick Draper

Description

Implement the code to support the directives described in this document.

Change History

comment:1 Changed 6 years ago by Martyn Gigg

  • Status changed from new to assigned

comment:2 Changed 6 years ago by Martyn Gigg

  • Status changed from assigned to inprogress

comment:3 Changed 6 years ago by Jay Rainey

Add working set of Sphinx extensions.

Refs #9521

Changeset: 36e8f20aa30e1aa8adb0caea01eee973145d5aac

comment:4 Changed 6 years ago by Martyn Gigg

Add README and initial start on style guide text.

Refs #9521

Changeset: 5cd6fe34979badbf9535cafa1fbd0acc2c280603

comment:5 Changed 6 years ago by Jay Rainey

Update screenshot method to add CSS class to image. Refs #9521.

  • This is required to easily style the image, e.g. alignment.

Changeset: 7e598c2cfaa0f64e96b916001ef48b40c2b133a5

comment:6 Changed 6 years ago by Jay Rainey

Removed title from categories. Refs #9521.

Changeset: c57778437f19f50c81890a6032b65dfcb3b2a3c0

comment:7 Changed 6 years ago by Jay Rainey

Added local table of content to algorithm. Refs #9521.

Changeset: a7c12f3fdb4117ef8925c8191876abafde8094b8

comment:8 Changed 6 years ago by Jay Rainey

Use figure rather than image. Refs #9521.

  • This allows a caption to be added that contains the algorithms name, to make the screenshot's purpose clearer.

Changeset: 48610385b4b9f53d157ee007421039eeb01b4e0a

comment:9 Changed 6 years ago by Martyn Gigg

Hard code section header names rather than using the module titles

It's clearer where the section names come from and avoids any unwanted module qualifications when the directives become part of a package. Refs #9521

Changeset: b6b077513881c40c06730f474395c23653ca61bb

comment:10 Changed 6 years ago by Martyn Gigg

Add supporting code to generate screenshot in algorithm directive

Refs #9521

Changeset: 844db760888c7851322ace3eed1d4bd84ca02b33

comment:11 Changed 6 years ago by Martyn Gigg

Add gitignore & README for images directory.

Refs #9521

Changeset: 67a2c8a142cf1c0cef19674bdc378991a06641e7

comment:12 Changed 6 years ago by Jay Rainey

Add initial config file. Refs #9521.

Changeset: 22ad91bb4eec29e18f84356bc7c4908a4d52c059

comment:13 Changed 6 years ago by Jay Rainey

Add custom styles to sphinx-bootstrap theme. Refs #9521.

Changeset: 447cfb33636868a16cf55893373bc4e694ee7f28

comment:14 Changed 6 years ago by Jay Rainey

Create empty globaltoc template to remove button in nav. Refs #9521.

Changeset: d8c9f62fffe483b422b21a9032e27a5984cc82be

comment:15 Changed 6 years ago by Jay Rainey

Moved static and template folder to source. Refs #9521.

Changeset: 98c9929576b2190928e93f68414bb0a8e6f310c1

comment:16 Changed 6 years ago by Martyn Gigg

Add in html logo and tweak css

Refs #9521

Changeset: dfae6838887624deca01b217b8ef14bb32f240ca

comment:17 Changed 6 years ago by Martyn Gigg

Require versioned algorithm files

Implements a test for a simple redirect system to the highest version Refs #9521

Changeset: ca642c60af0897107d209556799f34e4744a067d

comment:18 Changed 6 years ago by Martyn Gigg

Protect screenshot capture if the GUI is not present.

Refs #9521

Changeset: db26bfe12078e0fad461cb7e0b9e3702223f3879

comment:19 Changed 6 years ago by Martyn Gigg

Forget to add category & redirect templates

Refs #9521

Changeset: 72808a0405c0eb370d1bd6f58810e3978c7d0a6d

comment:20 Changed 6 years ago by Martyn Gigg

Track highest versions of algorithms encountered

Redirect pages are created that point from a page using the plain name to the highest version page Refs #9521

Changeset: a082fb2675541f88b2d77051c72291136fcc6260

comment:21 Changed 6 years ago by Martyn Gigg

Purge category information before parsing document.

Refs #9521

Changeset: 26b4db4ce226983487b3f878eee3ea1b92a2b0c5

comment:22 Changed 6 years ago by Martyn Gigg

Only insert alias section if one exists.

Refs #9521

Changeset: 3d92c9a1b0d8d5ec36c86156c74a5350dd7f6577

comment:23 Changed 6 years ago by Martyn Gigg

Add deprecation message if neccesary

Also regorganised to base to give easier access to algorithm name/version. Refs #9521

Changeset: dd2043aaf2f08730fa7581ae7b38525020d05a63

comment:24 Changed 6 years ago by Martyn Gigg

Update style of directives to be more similar to each other.

Refs #9521

Changeset: 8727d697ed4694ad07006900e907e58700a94f6b

comment:25 Changed 6 years ago by Martyn Gigg

Add highestVersion() method to AlgorithmFactory

It provides easy access to the highest version of an algorithm currently registered. Refs #9521

Changeset: 920a2dbb90b5ee9e150b9e3ac83b1b553d477b36

comment:26 Changed 6 years ago by Martyn Gigg

Only add Sphinx ref link if algorithm is highest version

Refs #9521

Changeset: 20815b842504b9436c1a8c0b2ccc60c677d2ec14

comment:27 Changed 6 years ago by Martyn Gigg

Fix bootstrap navbar size issue.

Also replace logo with cropped version to take up less space. Refs #9521

Changeset: 152593258835669b696fd677539b83033686d7a2

comment:28 Changed 6 years ago by Martyn Gigg

Extend our layout class in category not the default.

Refs #9521

Changeset: 8373eb4d8a8076c202fd62962b9e5409f908d95f

comment:29 Changed 6 years ago by Martyn Gigg

Add docs-html target to CMake

Only added if Sphinx can be found. Refs #9521

Changeset: afbdb0365f51a5ad8d7cfe7636b403e1f80f03b3

comment:30 Changed 6 years ago by Martyn Gigg

Update docs README to include package requirements

Refs #9521

Changeset: 0f669bf033552a1a0bf4afe4c504b6445b1075e4

comment:31 Changed 6 years ago by Martyn Gigg

Use reST for the style guide.

Refs #9521

Changeset: be9f0c2cee84281d66953653b4991ede6305ca4e

comment:32 Changed 6 years ago by Martyn Gigg

Delete all screenshot images that were generated in the source dir

Sphinx requires them in the source tree to build properly but we don't want them around all of the time. Refs #9521

Changeset: edcf7fd044367b356bc82300e93f67fc90bb05b6

comment:33 Changed 6 years ago by Martyn Gigg

Fix property descriptions that span multiple lines

Simply replaces the new line with a space and lets the output formatter take care of displaying it. Refs #9521

Changeset: ce0d5734c322493776ad838adf65a8e8b054bf80

comment:34 Changed 6 years ago by Martyn Gigg

Re-enable content for mobile devices

It may not look the best at the moment but it's better than not being able to see it at all.

Refs #9521

Changeset: d48a5a621ce3817fdb9e8370efc26c5695dea13f

comment:35 Changed 6 years ago by Martyn Gigg

  • Status changed from inprogress to verify
  • Resolution set to fixed

Fix MantidPlot screenshot test.

The extension is now expected as part of the filename.

Refs #5321

Changeset: 396c2ad714fed2c0d39e829a0eee032906faa0d7

comment:36 Changed 6 years ago by Martyn Gigg

Last commit went against the wrong ticket.

comment:37 Changed 6 years ago by Martyn Gigg

  • Status changed from verify to reopened
  • Resolution fixed deleted

comment:38 Changed 6 years ago by Martyn Gigg

  • Status changed from reopened to verify
  • Resolution set to fixed

Branch: feature/9521_sphinx_doc_directives

This doesn't include any rst source as they'll come along later.

comment:39 Changed 6 years ago by Jay Rainey

  • Status changed from verify to verifying
  • Tester set to Jay Rainey

comment:40 Changed 6 years ago by Martyn Gigg

Remove unrequired algm_categories directive.

The standard 'categories' one can now be used in both cases. Refs #9521

Changeset: 206afa4a34e7ff0858ff43050c6fb68e47869635

comment:41 Changed 6 years ago by Martyn Gigg

Simplify creating the screenshots.

They are no created in a directory specified by an environment variable so that they don't have to touch the source directory. Refs #9521

Changeset: f3d39a1988d3ddd75939725c401e078d2aaca0d3

comment:42 Changed 6 years ago by Martyn Gigg

Allow older versions of algorithms to be referenced

Refs #9521

Changeset: 6aa58fbd775f3b325b520e9e5988c3c81aa59996

comment:43 Changed 6 years ago by Martyn Gigg

Add docs-test target to run sphinx doctests

Refs #9521

Changeset: c5db858279a5efa8e7febcaffe02f63a6f027146

comment:44 Changed 6 years ago by Martyn Gigg

Use cmake variable to set MantidPlot used for docs build

This will allow us to use a package rather than a fresh build if necessary. Refs #9521

Changeset: f02531e224fb248793c7e1062472292a7624187e

comment:45 Changed 6 years ago by Nick Draper

  • Status changed from verifying to verify
  • Tester Jay Rainey deleted

comment:46 Changed 6 years ago by Nick Draper

  • Status changed from verify to verifying
  • Tester set to Nick Draper

comment:47 Changed 6 years ago by Nick Draper

  • Status changed from verifying to closed

Merge remote-tracking branch 'origin/feature/9521_sphinx_doc_directives'

Full changeset: 65343c800c53ee9a8bf626159992116325b280ed

comment:48 Changed 5 years ago by Stuart Campbell

This ticket has been transferred to github issue 10364

Note: See TracTickets for help on using tickets.