[CXX-1000] Migrate documentation to GitHub Pages Created: 19/Aug/16  Updated: 19/Oct/16  Resolved: 28/Sep/16

Status: Closed
Project: C++ Driver
Component/s: Documentation
Affects Version/s: None
Fix Version/s: 3.0.3

Type: Task Priority: Major - P3
Reporter: David Golden Assignee: David Golden
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by CXX-1048 Improve legacy build documentation Closed
Related
is related to CXX-996 Generated API docs have broken "logo"... Closed
is related to CXX-1013 unrendered markdown as title in the docs Closed
is related to DOCS-8894 Point all C++ Driver documentation to... Closed

 Description   

Our plan is to migrate all documentation to GitHub pages. This includes:

  • The new Driver Playbook intro docs (rendered by Hugo)
  • CXX11 API docs (doxygen)
  • Legacy API docs (doxygen)

The Driver Playbook has an open code review from the docs team and needs to be migrated into a "docs" directory in the master repo.

We then need automation to build and deploy updated docs on demand. We should have the capability to build and deploy documentation for legacy branches and point release branches/tags.



 Comments   
Comment by Githook User [ 29/Sep/16 ]

Author:

{u'username': u'xdg', u'name': u'David Golden', u'email': u'xdg@xdg.me'}

Message: CXX-1000 Migrate documentation to GitHub Pages

This commit creates a docs/ directory containing a general set
of documentation files for use with the hugo static site generator.
The site generated from these files will be deployed to GitHub Pages
and supersede the current wiki.

It also provides CMake targets to generate and deploy both this static
manual and the doxygen generated API documentation sites for all legacy and
mongocxx releases.

The doxygen configurations are generated dynamically to ensure that
documentation from old releases uses the same formatting and "front page"
content as current releases.

The site deployment targets do not create symlinks, which are necessary for
proper "permalinks" to the latest documentation. These must be added
manually:

  • /api/mongocxx-v3 -> /api/mongocxx-3.0.x (for latest x in v3 series)
  • /api/legacy-v1 -> /api/legacy-1.1.x (for latest x in v1 series)
  • /api/current -> /api/mongocxx-v3

For symlinks to work, there must be a `.nojekyll` file at the top of
the GitHub Pages site.
Branch: 3.1-dev
https://github.com/mongodb/mongo-cxx-driver/commit/428607a5dadcbc8de7069b39133572a48a6b87ce

Comment by David Golden [ 28/Sep/16 ]

Wiki and README pages updated. The wiki pages point to the top of the manual rather than subpages, so that we don't wind up with broken wiki links if we choose to reorganize the manual layout later.

Comment by David Golden [ 28/Sep/16 ]

Oops. Shouldn't resolve this until README and wiki pages point to new docs.

Comment by Githook User [ 28/Sep/16 ]

Author:

{u'username': u'xdg', u'name': u'David Golden', u'email': u'xdg@xdg.me'}

Message: CXX-1000 Migrate documentation to GitHub Pages

This commit creates a docs/ directory containing a general set
of documentation files for use with the hugo static site generator.
The site generated from these files will be deployed to GitHub Pages
and supersede the current wiki.

It also provides CMake targets to generate and deploy both this static
manual and the doxygen generated API documentation sites for all legacy and
mongocxx releases.

The doxygen configurations are generated dynamically to ensure that
documentation from old releases uses the same formatting and "front page"
content as current releases.

The site deployment targets do not create symlinks, which are necessary for
proper "permalinks" to the latest documentation. These must be added
manually:

  • /api/mongocxx-v3 -> /api/mongocxx-3.0.x (for latest x in v3 series)
  • /api/legacy-v1 -> /api/legacy-1.1.x (for latest x in v1 series)
  • /api/current -> /api/mongocxx-v3

For symlinks to work, there must be a `.nojekyll` file at the top of
the GitHub Pages site.
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/428607a5dadcbc8de7069b39133572a48a6b87ce

Comment by David Golden [ 21/Sep/16 ]

https://github.com/mongodb/mongo-cxx-driver/pull/539

Comment by David Golden [ 31/Aug/16 ]

Potentially useful references:

Generated at Wed Feb 07 22:01:04 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.