Skip to content

Commit de43243

Browse files
jwinkle8jwinkle8
authored
feat: add doc snippets (#593)
1 parent 0f1f8c2 commit de43243

File tree

14 files changed

+2325
-3
lines changed

14 files changed

+2325
-3
lines changed

‎doc/source/api/ansys/stk/core/stkobjects/CoverageDefinition.rst‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,41 @@ Overview
5454

5555

5656

57+
Examples
58+
--------
59+
60+
Set the Coverage Interval to an object's availability Analysis interval
61+
62+
.. code-block:: python
63+
64+
# Satellite satellite: Satellite object
65+
# CoverageDefinition coverage: Coverage object
66+
satVGT: "AnalysisWorkbenchComponentProvider" = IStkObject(satellite).analysis_workbench_components
67+
intervals: "TimeToolTimeIntervalGroup" = satVGT.time_intervals
68+
AvailTimeSpan: "ITimeToolTimeInterval" = intervals.item("AvailabilityTimeSpan")
69+
IntResult: "TimeToolTimeIntervalResult" = AvailTimeSpan.find_interval()
70+
coverage.interval.analysis_interval.set_start_and_stop_times(IntResult.interval.start, IntResult.interval.stop)
71+
72+
73+
Set Advanced Settings for Coverage
74+
75+
.. code-block:: python
76+
77+
# CoverageDefinition coverage: Coverage object
78+
advanced: "CoverageAdvancedSettings" = coverage.advanced
79+
advanced.recompute_automatically = False
80+
advanced.data_retention = CoverageDataRetention.ALL_DATA
81+
advanced.save_mode = DataSaveMode.SAVE_ACCESSES
82+
83+
84+
Compute Coverage
85+
86+
.. code-block:: python
87+
88+
# CoverageDefinition coverage: Coverage object
89+
coverage.compute_accesses()
90+
91+
5792
Import detail
5893
-------------
5994

‎doc/source/api/ansys/stk/core/stkobjects/IAccessConstraint.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,21 @@ Overview
3232
- Maximum relative motion used in adaptive sampling.
3333

3434

35+
Examples
36+
--------
37+
38+
Add an Exclusion Zone access constraint
39+
40+
.. code-block:: python
41+
42+
# AccessConstraintCollection accessConstraints: Access Constraint collection
43+
excludeZone: "AccessConstraintLatitudeLongitudeZone" = accessConstraints.add_named_constraint('ExclusionZone')
44+
excludeZone.maximum_latitude = 45
45+
excludeZone.minimum_latitude = 15
46+
excludeZone.minimum_longitude = -75
47+
excludeZone.maximum_longitude = -35
48+
49+
3550
Import detail
3651
-------------
3752

‎doc/source/getting-started.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,26 @@ This page helps you quickly get started with PySTK. It lists all the
55
prerequisites and guides you step by step to install the library on your
66
platform.
77

8-
.. grid:: 3
8+
.. grid:: 1 1 3 3
99

1010
.. grid-item-card:: :fa:`info-circle` About PySTK
1111
:link: getting-started/about
1212
:link-type: doc
13+
:padding: 2 2 2 2
1314

1415
About the next generation Python API for STK
1516

1617
.. grid-item-card:: :fa:`tasks` Prerequisites
1718
:link: getting-started/prerequisites
1819
:link-type: doc
20+
:padding: 2 2 2 2
1921

2022
What you need prior installing PySTK
2123

2224
.. grid-item-card:: :fa:`download` Install
2325
:link: getting-started/install
2426
:link-type: doc
27+
:padding: 2 2 2 2
2528

2629
Guidelines on how to install PySTK in your system
2730

‎doc/source/user-guide.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,13 @@ User guide
99

1010
Guidelines on how to migrate your code to PySTK
1111

12+
.. grid-item-card:: :fa:`clone` Code snippets
13+
:link: user-guide/code-snippets
14+
:link-type: doc
15+
:padding: 2 2 2 2
16+
17+
Learn how to automate the most common STK capabilities with PySTK
18+
1219

1320

1421
.. toctree::
@@ -17,3 +24,4 @@ User guide
1724

1825

1926
Migration <user-guide/migration>
27+
Code snippets <user-guide/code-snippets>

‎doc/source/user-guide/code-snippets.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
PySTK code snippets
2+
###################
3+
4+
The following code snippets demonstrate tasks that are commonly encountered when working with the PySTK API.
5+
6+
How do I
7+
========
8+
9+
STK Objects
10+
Access
11+
- :ref:`Add an exclusion zone access constraint <AddExclusionZoneConstraint>`
12+
Coverage Definition
13+
- :ref:`Set the coverage interval to an object's availability analysis interval <CoverageInterval>`
14+
- :ref:`Set advanced settings for coverage <CoverageAdvanced>`
15+
- :ref:`Compute coverage <CoverageCompute>`
16+
17+
18+
.. _AddExclusionZoneConstraint:
19+
20+
Add an exclusion zone access constraint
21+
=======================================
22+
23+
.. code-block:: python
24+
25+
# AccessConstraintCollection accessConstraints: Access Constraint collection
26+
excludeZone: "AccessConstraintLatitudeLongitudeZone" = accessConstraints.add_named_constraint('ExclusionZone')
27+
excludeZone.maximum_latitude = 45
28+
excludeZone.minimum_latitude = 15
29+
excludeZone.minimum_longitude = -75
30+
excludeZone.maximum_longitude = -35
31+
32+
.. _CoverageInterval:
33+
34+
Set the coverage interval to an object's availability analysis interval
35+
=======================================================================
36+
37+
.. code-block:: python
38+
39+
# Satellite satellite: Satellite object
40+
# CoverageDefinition coverage: Coverage object
41+
satVGT: "AnalysisWorkbenchComponentProvider" = IStkObject(satellite).analysis_workbench_components
42+
intervals: "TimeToolTimeIntervalGroup" = satVGT.time_intervals
43+
AvailTimeSpan: "ITimeToolTimeInterval" = intervals.item("AvailabilityTimeSpan")
44+
IntResult: "TimeToolTimeIntervalResult" = AvailTimeSpan.find_interval()
45+
coverage.interval.analysis_interval.set_start_and_stop_times(IntResult.interval.start, IntResult.interval.stop)
46+
47+
.. _CoverageAdvanced:
48+
49+
Set advanced settings for coverage
50+
==================================
51+
52+
.. code-block:: python
53+
54+
# CoverageDefinition coverage: Coverage object
55+
advanced: "CoverageAdvancedSettings" = coverage.advanced
56+
advanced.recompute_automatically = False
57+
advanced.data_retention = CoverageDataRetention.ALL_DATA
58+
advanced.save_mode = DataSaveMode.SAVE_ACCESSES
59+
60+
.. _CoverageCompute:
61+
62+
Compute coverage
63+
================
64+
65+
.. code-block:: python
66+
67+
# CoverageDefinition coverage: Coverage object
68+
coverage.compute_accesses()

‎src/ansys/stk/core/stkobjects/__init__.py‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10652,7 +10652,19 @@ def time(self, value:float) -> None:
1065210652
agcls.AgTypeNameMap["IVehicleLeadTrailDataTime"] = IVehicleLeadTrailDataTime
1065310653

1065410654
class IAccessConstraint(object):
10655-
"""AccessConstraint used to access the AccessConstraint attributes."""
10655+
"""
10656+
AccessConstraint used to access the AccessConstraint attributes.
10657+
10658+
Examples
10659+
--------
10660+
Add an Exclusion Zone access constraint:
10661+
>>> # AccessConstraintCollection accessConstraints: Access Constraint collection
10662+
>>> excludeZone: "AccessConstraintLatitudeLongitudeZone" = accessConstraints.add_named_constraint('ExclusionZone')
10663+
>>> excludeZone.maximum_latitude = 45
10664+
>>> excludeZone.minimum_latitude = 15
10665+
>>> excludeZone.minimum_longitude = -75
10666+
>>> excludeZone.maximum_longitude = -35
10667+
"""
1065610668

1065710669
_num_methods = 9
1065810670
_vtable_offset = IUnknown._vtable_offset + IUnknown._num_methods
@@ -69693,7 +69705,31 @@ def __setattr__(self, attrname, value):
6969369705
agcls.AgTypeNameMap["LineTargetGraphics3D"] = LineTargetGraphics3D
6969469706

6969569707
class CoverageDefinition(IStkObject, ILifetimeInformation, SupportsDeleteCallback):
69696-
"""Coverage definition properties."""
69708+
"""
69709+
Coverage definition properties.
69710+
69711+
Examples
69712+
--------
69713+
Set the Coverage Interval to an object's availability Analysis interval:
69714+
>>> # Satellite satellite: Satellite object
69715+
>>> # CoverageDefinition coverage: Coverage object
69716+
>>> satVGT: "AnalysisWorkbenchComponentProvider" = IStkObject(satellite).analysis_workbench_components
69717+
>>> intervals: "TimeToolTimeIntervalGroup" = satVGT.time_intervals
69718+
>>> AvailTimeSpan: "ITimeToolTimeInterval" = intervals.item("AvailabilityTimeSpan")
69719+
>>> IntResult: "TimeToolTimeIntervalResult" = AvailTimeSpan.find_interval()
69720+
>>> coverage.interval.analysis_interval.set_start_and_stop_times(IntResult.interval.start, IntResult.interval.stop)
69721+
69722+
Set Advanced Settings for Coverage:
69723+
>>> # CoverageDefinition coverage: Coverage object
69724+
>>> advanced: "CoverageAdvancedSettings" = coverage.advanced
69725+
>>> advanced.recompute_automatically = False
69726+
>>> advanced.data_retention = CoverageDataRetention.ALL_DATA
69727+
>>> advanced.save_mode = DataSaveMode.SAVE_ACCESSES
69728+
69729+
Compute Coverage:
69730+
>>> # CoverageDefinition coverage: Coverage object
69731+
>>> coverage.compute_accesses()
69732+
"""
6969769733

6969869734
_num_methods = 12
6969969735
_vtable_offset = IUnknown._vtable_offset + IUnknown._num_methods

‎tests/doc_snippets_tests/access_snippets/access_snippets.py‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
from test_util import *
2+
from ansys.stk.core.stkobjects import *
3+
4+
# Add path to the parent directory to use some common utilities
5+
sys.path.insert(1, os.path.join(os.path.dirname(os.path.realpath(__file__)), ".."))
6+
from code_snippets_test_base import *
7+
from code_snippet_decorator import *
8+
9+
10+
class AccessSnippets(CodeSnippetsTestBase):
11+
def __init__(self, *args, **kwargs):
12+
super(AccessSnippets, self).__init__(*args, **kwargs)
13+
14+
satellite: "Satellite" = None
15+
accessConstraints: "AccessConstraintCollection" = None
16+
17+
@staticmethod
18+
def setUpClass():
19+
CodeSnippetsTestBase.Initialize()
20+
21+
@staticmethod
22+
def tearDownClass():
23+
CodeSnippetsTestBase.Uninitialize()
24+
25+
def setUp(self):
26+
AccessSnippets.satellite: "Satellite" = Satellite(
27+
CodeSnippetsTestBase.m_Root.current_scenario.children.new(STKObjectType.SATELLITE, "satellite")
28+
)
29+
propagator: "PropagatorTwoBody" = AccessSnippets.satellite.propagator
30+
propagator.propagate()
31+
AccessSnippets.accessConstraints: "AccessConstraintCollection" = AccessSnippets.satellite.access_constraints
32+
33+
def tearDown(self):
34+
CodeSnippetsTestBase.m_Root.current_scenario.children.unload(STKObjectType.SATELLITE, "satellite")
35+
AccessSnippets.satellite = None
36+
37+
def test_TestAddExclusionZoneConstraintSnippet(self):
38+
self.TestAddExclusionZoneConstraintSnippet(CodeSnippetsTestBase.m_Root, AccessSnippets.accessConstraints)
39+
40+
@code_snippet(
41+
name="AddExclusionZoneConstraint",
42+
description="Add an Exclusion Zone access constraint",
43+
category="STK Objects | Access",
44+
eid="STKObjects~IAgAccessConstraint",
45+
)
46+
def TestAddExclusionZoneConstraintSnippet(
47+
self, root: "StkObjectRoot", accessConstraints: "AccessConstraintCollection"
48+
):
49+
# AccessConstraintCollection accessConstraints: Access Constraint collection
50+
excludeZone: "AccessConstraintLatitudeLongitudeZone" = accessConstraints.add_named_constraint("ExclusionZone")
51+
excludeZone.maximum_latitude = 45
52+
excludeZone.minimum_latitude = 15
53+
excludeZone.minimum_longitude = -75
54+
excludeZone.maximum_longitude = -35

‎tests/doc_snippets_tests/app_provider.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
class TestTarget:
2+
eStk = 0
3+
eStkX = 1
4+
sStkXStandalone = 2
5+
eStkNoGfx = 3
6+
eStkGrpc = 4
7+
eStkRuntime = 5
8+
eStkRuntimeNoGfx = 6
9+
10+
11+
class IAgAppProvider:
12+
pass
13+
14+
15+
class IAgSTKXApplicationProvider:
16+
pass

‎tests/doc_snippets_tests/code_snippet_decorator.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
def code_snippet(name: str, description: str, category: str, eid: str):
2+
def decorator(func):
3+
func.name = name
4+
func.description = description
5+
func.category = category
6+
func.eid = eid
7+
return func
8+
9+
return decorator

‎tests/doc_snippets_tests/code_snippets_test_base.py‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
from test_util import *
2+
from ansys.stk.core.graphics import *
3+
from ansys.stk.core.stkobjects import *
4+
from ansys.stk.core.stkutil import *
5+
from ansys.stk.core.vgt import *
6+
7+
8+
class CodeSnippetsTestBase(TestBase):
9+
def __init__(self, *args, **kwargs):
10+
super(CodeSnippetsTestBase, self).__init__(*args, **kwargs)
11+
12+
m_Root: "StkObjectRoot" = None
13+
14+
@staticmethod
15+
def Initialize():
16+
TestBase.Initialize()
17+
CodeSnippetsTestBase.m_Root = TestBase.Application
18+
CodeSnippetsTestBase.SafeScenarioUnload()
19+
20+
TestBase.Application.new_scenario("CodeSnippetScenario")
21+
scenario: "Scenario" = Scenario(TestBase.Application.current_scenario)
22+
scenario.set_time_period("1 Jan 2012 12:00:00.000", "2 Jan 2012 12:00:00.000")
23+
24+
@staticmethod
25+
def InitializeWithNewScenario(makeNewScenario: bool):
26+
TestBase.Initialize()
27+
CodeSnippetsTestBase.m_Root = TestBase.Application
28+
CodeSnippetsTestBase.SafeScenarioUnload()
29+
if makeNewScenario:
30+
TestBase.Application.new_scenario("CodeSnippetScenario")
31+
scenario: "Scenario" = Scenario(TestBase.Application.current_scenario)
32+
scenario.set_time_period("1 Jan 2012 12:00:00.000", "2 Jan 2012 12:00:00.000")
33+
34+
@staticmethod
35+
def Uninitialize():
36+
CodeSnippetsTestBase.SafeScenarioUnload()
37+
CodeSnippetsTestBase.m_Root.units_preferences.reset_units()
38+
TestBase.Uninitialize()
39+
40+
@staticmethod
41+
def SafeScenarioUnload():
42+
if CodeSnippetsTestBase.m_Root.current_scenario != None:
43+
CodeSnippetsTestBase.m_Root.close_scenario()

0 commit comments

Comments
 (0)