Task #950
closed
Consolidate platform and plugin docs into a static site.
100%
Description
We currently host our documentation at Read The Docs (RTD), which has a few problems. We have had issues with RTD being inflexible with our workflows. Also, RTD tracks our users with Google Analytics, and has also begun injecting advertisements into our project documentation. The RTD template messes up the Pulp sidebar and makes it difficult for users to navigate our documentation. Also RTD places banners in strange places saying documentation is out of date when it isn't. Finally it prevents us from releasing docs with our beta and RC builds easily. It's just difficult for us to work with.
Also all the docs are in their own "sites" which makes it very difficult to determine what Pulp does. These should be consolidated.
Make a prototype:
- Make a Jenkins builder which publishes documentation nightly as a periodic job. This should use the Jenkins job builder template in pulp_packaging.
- The Jenkins job builder should clone and build docs for platform and all plugins nightly
- Send the prototype and the rough migration plan to the community and the rest of the development team for comment
- Consolidate all plugins and platform docs into one site.
Additional Requirements:
- easy linking between X.Y versions of Pulp (like the existing docs do today and the Django docs for example)
- preserve the intersphinx structure we have today. This needs to continue to work
- Fix any broken links that don't use intersphinx to resolve the link URL. This should be in its own PR that will be pushed as part of the migration plan.
- The ability to publish docs for a specific alpha/beta/RC
Related issues
Updated by bmbouter over 9 years ago
- Related to Issue #840: Beta and release candidate documentation is not available added
Updated by bmbouter over 9 years ago
- Related to Task #831: Incorrect banners on RTD pages added
Updated by bmbouter over 9 years ago
- Subject changed from Develop a plan to host our docs in OpenShift to Prototype hosting our docs in OpenShift
- Description updated (diff)
Updated by bmbouter over 8 years ago
- Subject changed from Prototype hosting our docs in OpenShift to Consolidate platform and plugin docs into a static site.
- Description updated (diff)
Updated by bmbouter over 8 years ago
- Blocks Task #1888: Deploy the statically built docs to OpenShift added
Updated by mhrivnak over 8 years ago
- Sprint/Milestone set to 20
- Groomed changed from No to Yes
Added by bmbouter over 8 years ago
Added by bmbouter over 8 years ago
Revision 2fa42342 | View on GitHub
Revert "Adds a skeleton sphinx docs project for crane."
This reverts commit 961e0b49ebb6994774004dbb63509b5202c8e5bf.
This is being moved to 2.0-release and then merged forward to master.
Added by bmbouter over 8 years ago
Revision d33d5e59 | View on GitHub
Adds a skeleton sphinx docs project for crane.
This allows the docs builder jobs in Jenkins to build the docs for all projects in the same way (with Sphinx).
The fixedbugs has been tested by test building:
:fixedbugs:`2.0.0`
Also make html in the docs directory should not produce errors.
Added by bmbouter over 8 years ago
Revision 4ee47370 | View on GitHub
Migrates README.rst content into the sphinx built project
-
Maintains a basic description in the README which links to the rest content in it's new location.
-
Also fixes several formatting errors which Sphinx identified This causes
make htmlto produce html output that looks good without any warnings or errors. -
Adds a flake8 ignore statement to ignore the docs/conf.py file
Prior to this the build process would fail with:
Sphinx error:
master file /home/bmbouter/devel/working/crane/docs/index.rst not found
This commit is designed to restructure the current docs so it is being merged to 2.0-release and merged forward from there.
Added by bmbouter over 8 years ago
Revision 14fb8928 | View on GitHub
Configures Sphinx docs config to not look for static media
Prior to this fix when building the docs you would see a warning like:
html_static_path entry u'/path/to/pulp_ostree/docs/_static' does not exist
Added by bmbouter over 8 years ago
Revision cd640564 | View on GitHub
Fixes pulp_rpm sphinx build errors and warnings.
Added by bmbouter over 8 years ago
Revision 595a6b0f | View on GitHub
Fixes docs build errors and warnings
make html now builds cleanly without any errors or warnings.
Added by bmbouter over 8 years ago
Revision 7fa1527d | View on GitHub
Fixes platform docs build warnings/errors and compilation of images
- Docs build without any warnings or errors
- Enables strict building in python-sphinx project
- Digram sources moved to a sphinx project level directory
- Pre-made images moved to a sphinx project level directory
- Diagrams compile and cannot be saved back to the repo
Added by bmbouter over 8 years ago
Revision 7fa1527d | View on GitHub
Fixes platform docs build warnings/errors and compilation of images
- Docs build without any warnings or errors
- Enables strict building in python-sphinx project
- Digram sources moved to a sphinx project level directory
- Pre-made images moved to a sphinx project level directory
- Diagrams compile and cannot be saved back to the repo
Added by bmbouter over 8 years ago
Revision ac67da13 | View on GitHub
Fixes formatting error in 2.3 release notes
This was recently intorduced when the 2.3 release notes were adjusted during the 2.8.3 release.
Added by bmbouter over 8 years ago
Revision ac67da13 | View on GitHub
Fixes formatting error in 2.3 release notes
This was recently intorduced when the 2.3 release notes were adjusted during the 2.8.3 release.
Added by bmbouter over 8 years ago
Revision 61dd8f7e | View on GitHub
Fixes RTD pages which don't build plantuml images at build time.
These images were commited before in the repo with commit ab1e5c833d3e928252eef0b4b6ff05d06b1a504c. They are being brought back so that read the docs can have static images to use.
git already knows about these images so there is no additional storage space used by this commit.
This will be merged to 2.8-release -> 2.8-dev -> master
The future build machinery is introduced with 7fa1527d419a2c8f20979c145a8e0559c7587218
and will build all .dot diagrams freshly with each docs build.
Once we no longer use Read the Docs we will remove these two
images from _static and revert the .. image:: to use the
images available at build time in the _diagrams directory.
Added by bmbouter over 8 years ago
Revision 61dd8f7e | View on GitHub
Fixes RTD pages which don't build plantuml images at build time.
These images were commited before in the repo with commit ab1e5c833d3e928252eef0b4b6ff05d06b1a504c. They are being brought back so that read the docs can have static images to use.
git already knows about these images so there is no additional storage space used by this commit.
This will be merged to 2.8-release -> 2.8-dev -> master
The future build machinery is introduced with 7fa1527d419a2c8f20979c145a8e0559c7587218
and will build all .dot diagrams freshly with each docs build.
Once we no longer use Read the Docs we will remove these two
images from _static and revert the .. image:: to use the
images available at build time in the _diagrams directory.
Added by bmbouter over 8 years ago
Revision 59313dd4 | View on GitHub
Enables strict mode for sphinx docs builds
This causes errors to be noticed by the Jenkins job which is the motivation for this change.
Added by bmbouter over 8 years ago
Revision 1192684c | View on GitHub
Enables strict mode for sphinx docs builds
This causes errors to be noticed by the Jenkins job which is the motivation for this change.
Added by bmbouter over 8 years ago
Revision 1192684c | View on GitHub
Enables strict mode for sphinx docs builds
This causes errors to be noticed by the Jenkins job which is the motivation for this change.
Added by Brian Bouterse over 8 years ago
Revision 1192684c | View on GitHub
Enables strict mode for sphinx docs builds
This causes errors to be noticed by the Jenkins job which is the motivation for this change.
Added by Brian Bouterse over 8 years ago
Revision 1192684c | View on GitHub
Enables strict mode for sphinx docs builds
This causes errors to be noticed by the Jenkins job which is the motivation for this change.
Added by bmbouter over 8 years ago
Revision 2f5ac2b3 | View on GitHub
Enables strict mode for sphinx docs builds
This causes errors to be noticed by the Jenkins job which is the motivation for this change.
Added by bmbouter over 8 years ago
Revision c8ff0803 | View on GitHub
Enables strict mode for sphinx docs builds
This causes errors to be noticed by the Jenkins job which is the motivation for this change.
Added by bmbouter over 8 years ago
Revision e57e6e60 | View on GitHub
Enables strict mode for sphinx docs builds
This causes errors to be noticed by the Jenkins job which is the motivation for this change.
Added by bmbouter over 8 years ago
Revision 263183a8 | View on GitHub
Enables strict mode for sphinx docs builds
This causes errors to be noticed by the Jenkins job which is the motivation for this change.
Added by bmbouter over 8 years ago
Revision 0e9aa58f | View on GitHub
Adds intersphinx name for 'platform' to sphinx config
The plugins refer to platform using the intersphinx keyword 'platform'. As the plugin content will start being built as one sphinx project, the platform sphinx must also support the 'platform' keyword.
Added by bmbouter over 8 years ago
Revision 0e9aa58f | View on GitHub
Adds intersphinx name for 'platform' to sphinx config
The plugins refer to platform using the intersphinx keyword 'platform'. As the plugin content will start being built as one sphinx project, the platform sphinx must also support the 'platform' keyword.
Added by bmbouter over 8 years ago
Revision 5f86bba4 | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by bmbouter over 8 years ago
Revision 5f86bba4 | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by bmbouter over 8 years ago
Revision 6ccd256a | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by bmbouter over 8 years ago
Revision 6ccd256a | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by Brian Bouterse over 8 years ago
Revision 6ccd256a | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by Brian Bouterse over 8 years ago
Revision 6ccd256a | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by bmbouter over 8 years ago
Revision a3c01c70 | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by bmbouter over 8 years ago
Revision 50f14553 | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by bmbouter over 8 years ago
Revision 11fa1ff4 | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by bmbouter over 8 years ago
Revision 1eb3b376 | View on GitHub
Reverting strict mode so that Koji can build RPMs again
Koji does not allow for the loading of intersphinx inv files due to Mock's restriction of internet access during build time.
This will get reintroduced later after we have a better plan for how to handle intersphinx in our Koji environment.
Added by bmbouter over 8 years ago
Revision 14a5c084 | View on GitHub
Adds a docs builder Jenkins job
This job nightly build one sphinx project which includes platform and all plugins develped by the core dev team.
This job uses the docs-ownership so it has owners. It also uses the e-mail notify macro for owner notification on failure.
The version of each plugin is specified in the releases yaml files used by the build infrastructure. Each repo is cloned freshly with each build.
This job comes with additional rst files which are merged in prior to the build. This additional content organizes all of the other content which was not designed to be shown as one site.
It also deploys a robots.txt for the root of the docs site.
Added by bmbouter over 8 years ago
Revision a33455da | View on GitHub
Beta and RC docs should live at /en/x.y/testing/
Updated by bmbouter over 8 years ago
- Status changed from ASSIGNED to MODIFIED
- % Done changed from 0 to 100
Applied in changeset packaging:a33455da84f457264bc48a1ab8afd046f427e03f.
Updated by bmbouter over 8 years ago
- Status changed from MODIFIED to CLOSED - CURRENTRELEASE
- Platform Release deleted (
2.8.5)
This is already in production so I'm marking as closed.
Added by bmbouter over 8 years ago
Revision 82eea64a | View on GitHub
Adds analytics tracking to docs.pulpproject.org
.
Adds a skeleton sphinx docs project for crane.
This allows the docs builder jobs in Jenkins to build the docs for all projects in the same way (with Sphinx).
The fixedbugs has been tested by test building:
Also
make htmlin the docs directory should not produce errors.https://pulp.plan.io/issues/950 re #950