Skip to content
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

Fix paths in docs & update docs theme #1256

Open
wants to merge 27 commits into
base: master
Choose a base branch
from
Open

Conversation

MortGron
Copy link
Contributor

@MortGron MortGron commented Jun 20, 2023

Description

  • Fix paths in documentation so e.g. AsssetsAPI is shown as CogniteClient.assets.
  • Update docs theme. New theme have both left and right sidebar and lets one toggle between dark and light mode. Also includes copybutton in code examples.
  • Let each class and function have its own stub page. This structure is a consequence of the paths fix.
  • Each function and class now uses the summary line in their docstrings in the overview pages in the documentation. Thus there is a need to make sure that the summary lines are of high quality. Various summary lines have been altered in order to e.g. make sure that links are displayed correctly and for improved consistency.
  • Make sure year is updated in footer on each build of the docs: "2023, Cognite AS"
  • State required Python version on main page. Automatically retrieved from pyproject.toml.
  • Make docs dependencies an optional group in pyproject.tom.
  • Have links to Cogntie Hub, Academy and Developer Documentation. This should ideally be styled with cogs.js components, but this have not been implemented.

Things to consider

  • Whenever a class is made avaible in cognite.client.data_classes, this is the path shown in the docs. However, there does not seem to be consistency in which classes are avaible there and in e.g. cognite.client.data_classes.transformations etc.
  • Because the docs end up with +900 pages, the building time can get long. Thus building with multiple processes have been enabled, and slight optimization of GitHub Actions have been implemented.
  • No code in cognite.client is changed, except for when setting up accessors to build the docs. The latter is only done when an enviromental variable is set.

Example topic page:
image

Example method:
image

Example class:
image

Example instance object:
image

Example mobile view:
image

Checklist:

  • Tests added/updated.
  • Documentation updated. Documentation is generated from docstrings - these must be updated according to your change.
    If a new method has been added it should be referenced in cognite.rst in order to generate docs based on its docstring.
  • Changelog updated in CHANGELOG.md.
  • Version bumped. If triggering a new release is desired, bump the version number in _version.py and pyproject.toml per semantic versioning.

@codecov
Copy link

codecov bot commented Jun 20, 2023

Codecov Report

Merging #1256 (c5add64) into master (c0c8942) will decrease coverage by 0.58%.
The diff coverage is 12.79%.

@@            Coverage Diff             @@
##           master    #1256      +/-   ##
==========================================
- Coverage   90.42%   89.84%   -0.58%     
==========================================
  Files         110      110              
  Lines       13515    13595      +80     
==========================================
- Hits        12221    12215       -6     
- Misses       1294     1380      +86     
Files Changed Coverage Δ
cognite/client/_api/annotations.py 88.88% <ø> (ø)
cognite/client/_api/assets.py 94.87% <ø> (ø)
cognite/client/_api/data_modeling/containers.py 83.72% <ø> (ø)
cognite/client/_api/data_modeling/data_models.py 82.00% <ø> (ø)
cognite/client/_api/data_modeling/instances.py 82.32% <ø> (ø)
cognite/client/_api/data_modeling/spaces.py 85.36% <ø> (ø)
cognite/client/_api/data_modeling/views.py 86.95% <ø> (ø)
cognite/client/_api/data_sets.py 100.00% <ø> (ø)
cognite/client/_api/datapoints.py 96.30% <ø> (ø)
cognite/client/_api/datapoints_subscriptions.py 100.00% <ø> (ø)
... and 30 more

... and 1 file with indirect coverage changes

@MortGron MortGron marked this pull request as ready for review June 21, 2023 09:50
@MortGron MortGron requested review from a team as code owners June 21, 2023 09:50
@MortGron
Copy link
Contributor Author

MortGron commented Jul 4, 2023

@erlendvollset have changed the docs source files so that not every class, method etc. have to be explicitly listed.

@MortGron
Copy link
Contributor Author

@cognitedata/python-sdk-maintainers Could someone have a look at this?

This PR will get merge conflicts with master almost inevitable each time master is updated, and also potentially warnings and errors during building of the documentation. The latter because this PR relies heaviliy on autosummary in Sphinx which have more requirements to the formatting of docstrings. Therefore I will not spend time trying to keep this up to date with master unless requested.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants