-
Notifications
You must be signed in to change notification settings - Fork 102
Split the docs #1963
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.
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
Merged
Merged
Split the docs #1963
Changes from 29 commits
Commits
Show all changes
32 commits
Select commit
Hold shift + click to select a range
05b3e77
generate individual conf.py files
ni-jfitzger 278b784
Generate individual html documentation for each nimi-python package
ni-jfitzger 8a30afc
Clean up index page
ni-jfitzger cc7e3a1
Merge branch 'master' of https://github.com/ni-jfitzger/nimi-python i…
ni-jfitzger a004562
Add TODO for release process
ni-jfitzger 7aff573
Fix flake8 error
ni-jfitzger da434b8
Delete now-unused Root VERSION file
ni-jfitzger 071f701
Split LATEST_RELEASE file used for generating example.rst
ni-jfitzger 5a49372
Tweak wording; nimi-python is not a package, but a repo.
ni-jfitzger 786e64f
Add another TODO
ni-jfitzger ed2371b
Forgot to regenerate in a previous commit
ni-jfitzger b21627b
Update nidcpower readthedocs link
ni-jfitzger 512387c
Update readthedocs links
ni-jfitzger d664b20
Delete variable that I don't need after all
ni-jfitzger 51dd7c9
Remove TODO about leaving project name unchanged.
ni-jfitzger f402131
Remove CHANGELOG todo in build_release.py
ni-jfitzger bcb0e65
Remove update links todo
ni-jfitzger ae3dcf3
Use mako comments so that TODO only appears in one place
ni-jfitzger 2a16b74
Use api-specific start year for docs copyright date
ni-jfitzger aeee08d
FIgure out new release process and update build_release.py
ni-jfitzger 0cfc4a9
Undo all build_release.py changes
ni-jfitzger ea3c268
Add .readthedocs.yaml
ni-jfitzger 688ef4a
Restore original conf.py until we've updated the documentation for th…
ni-jfitzger 700e6db
Update the original index.rst to help users find documentation
ni-jfitzger b3f3a39
don't delete docs/conf.py during clean; we no longer codegen it
ni-jfitzger abb64b2
Update clean recipe to also delete .readthedocs.yaml
ni-jfitzger 87d893c
For new projects, add link to original project.
ni-jfitzger c90c81c
Update intersphinx_mapping format
ni-jfitzger 5b76980
Fix "Read the Docs" spelling
ni-jfitzger ffeeadc
lead with spaces on continued lines in modified GNU Make recipes
ni-jfitzger 449bd1c
Add empty line to end of conf.py
ni-jfitzger 0528f4b
Reword support.inc to not visibly mention nimi-python
ni-jfitzger File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| # .readthedocs.yaml | ||
| # Read the Docs configuration file | ||
| # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details | ||
| <% | ||
| config = template_parameters['metadata'].config | ||
| module_name = config['module_name'] | ||
| # All of the files used to configure and build docs and readthedocs are in these 2 folders | ||
| build_trigger_paths = f'docs/_static/ docs/{module_name}/' | ||
| conf_py_path = f'docs/{module_name}/conf.py' | ||
| %>\ | ||
|
|
||
| # Why Use A Configuration File? | ||
| # https://docs.readthedocs.io/en/stable/config-file/index.html | ||
| # The main advantages of using a configuration file over the web interface are: | ||
| # * Settings are per version rather than per project. | ||
| # * Settings live in your VCS. | ||
| # * They enable reproducible build environments over time. | ||
| # * Some settings are only available using a configuration file | ||
|
|
||
| # Required | ||
| version: 2 | ||
|
|
||
| # Set the version of Python and other tools you might need | ||
| build: | ||
| os: ubuntu-22.04 | ||
| tools: | ||
| python: "3.11" | ||
| jobs: | ||
| # pre_build: | ||
| # # Check for broken external links | ||
| # - python -m sphinx -b linkcheck -D linkcheck_timeout=1 docs/ _build/linkcheck | ||
| post_checkout: | ||
| # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition | ||
| # Build-cancellation rules are recommended for monorepos. | ||
| # Cancel building pull requests when there aren't changes in any of these paths: ${build_trigger_paths}. | ||
| # | ||
| # If there are no changes (git diff exits with 0) we force the command to return with 183. | ||
| # This is a special exit code on Read the Docs that will cancel the build immediately. | ||
| - | | ||
| if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/master -- ${build_trigger_paths}; | ||
| then | ||
| exit 183; | ||
| fi | ||
|
|
||
| # Have Read the Docs build documentation with Sphinx | ||
| sphinx: | ||
| builder: html | ||
| configuration: ${conf_py_path} | ||
|
|
||
| # If using Sphinx, optionally build your docs in additional formats such as PDF | ||
| formats: | ||
| - epub | ||
|
|
||
| # Optionally declare the Python requirements required to build your docs | ||
| ## TODO(ni-jfitzger): Create requirements file for docs to make builds reproducible. See https://github.com/ni/nimi-python/issues/1968 | ||
| ## Note: Our nimi-python readthedocs project used the defaults here: https://docs.readthedocs.io/en/stable/build-default-versions.html#external-dependencies | ||
| # python: | ||
| # install: | ||
| # - requirements: docs/requirements.txt |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| <% | ||
| '''This is a template for the module-specific .rst''' | ||
|
|
||
| config = template_parameters['metadata'].config | ||
| module_name = config['module_name'] | ||
| doc_header = f"{module_name} module" | ||
| %>\ | ||
| ${doc_header} | ||
| ${"=" * len(doc_header)} | ||
|
|
||
| .. include:: installation.inc | ||
|
|
||
| .. include:: ../_static/${module_name}_usage.inc | ||
|
|
||
| .. include:: toc.inc | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| <% | ||
| config = template_parameters['metadata'].config | ||
| doc_header = f"{config['driver_name']} Python API Documentation" | ||
| module_name = config['module_name'] | ||
| driver_name = config['driver_name'] | ||
| %>\ | ||
|
|
||
| ${doc_header} | ||
| ${"=" * len(doc_header)} | ||
|
|
||
| .. include:: ../_static/about_driver.inc | ||
|
|
||
| .. include:: ../_static/contributing.inc | ||
|
|
||
| .. include:: ../_static/support.inc | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 3 | ||
| :caption: Documentation | ||
|
|
||
| ${module_name} | ||
|
|
||
| Additional Documentation | ||
| ------------------------ | ||
|
|
||
| Refer to your driver documentation for device-specific information and detailed API documentation. | ||
|
|
||
| Refer to the `nimi-python Read the Docs project <https://nimi-python.readthedocs.io/en/stable/>`_ for documentation of versions 1.4.4 of the module or earlier. | ||
|
|
||
| .. include:: ../_static/license.inc | ||
|
|
||
| Indices and tables | ||
| ================== | ||
|
|
||
| * :ref:`genindex` | ||
| * :ref:`modindex` | ||
| * :ref:`search` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.