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.

Sign up for GitHub

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

Jump to bottom

Documentation improvements #142

Merged
merged 47 commits into from
Feb 19, 2024
Merged

Documentation improvements #142

merged 47 commits into from
Feb 19, 2024

Conversation

RKrahl
Copy link
Member

@RKrahl RKrahl commented Nov 22, 2023 •
edited
Loading

Improve the following things to improve in the documentation:

  • install instruction: explain how to verify the signature in order check the integrity of the source distribution. Point out that the installation using pip does not support this check. As a consequence, point to the distribution page at Github as the recommended download source, because it also offers the signature file (as opposed to PyPI).
  • better describe the the input file format for module icat.ingest as defined by the provided XSD files.
  • add more reference labels in order to get permalinks that could be stable across versions, in particular in the changelog, but maybe also at other places.
  • Fix ReST style of documentation sources: tabulation used for indentation, trailing white space, excessively long lines. Add GitHub action to check ReST style.

See the online documentation on Read the Docs for this branch.

Close #141

@RKrahl RKrahl added the documentation Improvements or additions to documentation label Nov 22, 2023
@RKrahl RKrahl mentioned this pull request Nov 22, 2023
Closed
@RKrahl RKrahl added this to the 1.3.0 milestone Dec 11, 2023
@RKrahl
Drop version constraint on Sphinx in RtD requirements,
cec2595 
e.g. essentially update tha Sphinx version used for building the
documentation
@RKrahl
Add sphinx_copybutton extension
4306390
@RKrahl
Add python scripts to contain the interactive code blocks from the
fafaa64 
tutorial
@RKrahl
Fix overly long lines in interactive tutorial examples
4e3bbe3
@RKrahl
Merge branch 'develop' into doc
9963fd5
@RKrahl
Restrict running ReST lint on push to branches develop and master
c941a9d
@RKrahl
Merge branch 'develop' into doc
8871a81
@RKrahl
Documentation fix: move a version changed note from module icat.ingest
16443e8 
to class icat.ingest.IngestReader
@RKrahl
Minor doc config fixes
8446200
@RKrahl
- Add a new section on file formats to the documentation
af28f5d 
- Move the subsection on ICAT data files from the icat.dumpfile module
  reference into the new file formats section
- Add a subsection on Metadata ingest files (only a section heading by
  now)
@RKrahl
Review introduction of ICAT data files section
3b9367e
@RKrahl
Some formulation review to the subsection on the structure of ICAT
33f8650 
data files
@RKrahl
Add simple ICAT data file examples
da2415f
@RKrahl
- Review documentation Section "ICAT data XML files", adding more
e62dc5a 
  inline examples
- Drop icatdump-simple-2.xml example, rename icatdump-simple-1.xml to
  icatdump-simple.xml
@RKrahl
Fix duplicate user entry in example ICAT data file
a472fc7
@RKrahl
- Review documentation Section "ICAT data YAML files"
b3e3052 
- Drop icatdump-simple-2.yaml example, rename icatdump-simple-1.yaml
  to icatdump-simple.yaml
@RKrahl
Review Section ICAT data files with respect to object references, add
acaff9d 
a Subsection References to ICAT objects and unique keys
@RKrahl
Rework Section ICAT data files once again
9c5085c
@RKrahl
Drop most of the docstring from module icat.dumpfile as this is now
0fc8b00 
much better explained in the online documentation
@RKrahl
Indicate in the documentation of icat.dumpfile which methods of class
504d091 
icat.dumpfile.DumpFileReader and class icat.dumpfile.DumpFileWriter
are abstract and thus need to implemented in the file format specific
backend
@RKrahl
Minor language fixes
a52714b
@RKrahl
Add first input to Section Metadata ingest files
f0112b8
@RKrahl
Minor language fixes
048a98c
@RKrahl RKrahl mentioned this pull request Jan 31, 2024
Merged
@RKrahl
Merge branch 'develop' into doc
569d2c2
@RKrahl
Add an example to the Metadata ingest files Section of the
dd7473f 
documentation
@RKrahl
Language fixes in the documentation
634a416
@RKrahl
Documentation fix: also the relation to DatasetType is added by
987f22e 
IngestReader
@RKrahl
- add a note on the versioning to metadata ingest file documentation
21235fa 
- move the versionchanged note about adding icatingest 1.1 from
  documentation on module ingest to the metadata ingest file page
@RKrahl
Update documentation for module icat.ingest taking into account the
c3d360b 
new file format documentation
@RKrahl
Another language fix
f2b9657
@RKrahl
Yet another language fix
9ad05b5
@RKrahl
Add kink anchors to the entries for each version in the changelog in
3eefef5 
order to provide more stable permalinks
@RKrahl
Dynamically create a file _meta.rst in the documentation source that
f1f2b73 
defines substitutions and download links for the latest source
distribution and signature file
@RKrahl
Review install instructions, explaining how to verify the signature
8f35940
@RKrahl
Fixup 8f35940: need to run doc/src/conf.py before doc8-check now
67b947c
@RKrahl
Aesthetic fix for rst-lint action: unshallow the checked out
2a827fd 
repository in order to get the correct version number in the
diagnostics
@RKrahl
Some tweaks in the install instructions:
848a474 
- Point out that a manual install does not automatically install
  dependencies,
- Removed yet another reference of PyPI yo get release versions from,
- Minor formulation fix.
@RKrahl RKrahl marked this pull request as ready for review February 19, 2024 17:15
@RKrahl RKrahl merged commit 6f6111f into develop Feb 19, 2024
1 check passed
@RKrahl RKrahl deleted the doc branch February 19, 2024 17:18
@RKrahl RKrahl mentioned this pull request Mar 4, 2024
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
1.3.0
Development

Successfully merging this pull request may close these issues.

Documentation improvements
1 participant
@RKrahl